FileMaker Data API Tools

Upgrade Guide

What to do, and what will look different, when you move from one version to the next. Each section lists only changes you can notice. For everything else, see the Changelog.

Upgrading from 1.7.0 to 1.8.0

Your profiles, saved queries and settings carry over; there is no data migration. No command or setting was removed or renamed, and no VS Code setting default changed; the on-screen changes you may notice are listed below. FileMaker Cloud sign-in with a Claris ID is still not supported; Cloud is untested.

Connection wizard: pick a CA certificate with Browse

The certificate section in the connection wizard has a Browse button that opens the system file picker, so you can choose a PEM, CRT or CER file instead of typing the path. The path you choose is still saved with the profile and is used by Test Connection.

Sign-in failures now say what to do

FileMaker error 212 now explains both possible causes: a mistyped password, or a privilege set that is missing the fmrest extended privilege, and it names the path in FileMaker Pro. Errors 212 and 9 also carry a Troubleshooting link in the Details report; other FileMaker codes keep their existing message.

What looks different on screen

The Record Editor lists fields in your layout's order instead of alphabetical order; the Record Viewer, find form and generated web pages follow the same field rules. Schema Diff opens with Show only changes ticked; clear the box to see unchanged fields too.

Web page generator: security update

The web page generator now uses Next.js 16.4.2, which fixes three published problems in Next.js: an image-handling flaw and a flaw in the use cache feature that could each run code, and a denial-of-service flaw. The extension itself did not use the affected parts, but an app you generated earlier keeps its old version. Run npm install next@16.4.2 in .fmweb/generated/runtime-next to update that app.

Rolling back

Use Install Specific Version... in the Extensions view to return to 1.7.0, or install its VSIX if you kept it (only tagged versions have a GitHub release). Profiles and saved data need no migration. Keep an untouched copy of exports before editing them. Version 1.7.0 has no Browse certificate picker, lists Record Editor fields alphabetically instead of in your layout's order, does not explain the fmrest cause for sign-in errors or link to Troubleshooting, and its web page generator still uses Next.js 16.3.8. Installing it does not undo record changes already sent to FileMaker.

Upgrading from 1.6.0 to 1.7.0

Your profiles, saved queries and settings carry over; there is no data migration. No command or setting was removed or renamed, and no setting default changed. AI features remain off by default. Read these changes before importing an old export or sharing a connection report. FileMaker Cloud sign-in with a Claris ID is not supported; Cloud is untested.

1. Batch updates ask how to handle newer changes

Keep the exported modId (or reserved __modId) column unchanged. After confirming an update, choose Check for newer changes (recommended) or Overwrite even if changed. The first sends each row's exported version to FileMaker. A record changed since export is skipped with error 306, appears in Jobs and Copy failures, and is not retried; other rows continue. The summary counts these skipped rows. Overwrite deliberately leaves out the version check and can replace someone else's newer work.

If no row has a version, a warning offers Continue or Cancel. Continuing cannot detect newer changes. If only some rows have versions, the prompt counts rows that cannot be checked. Export again to get versions, or review the unprotected rows yourself. A dry run sends no updates and shows version coverage, skipped columns and a sample of the values that would be sent. Duplicate record rows are skipped with a warning, and rows containing only skipped fields do not hide later changes. JSON record IDs and versions accept surrounding spaces; layout, script and field names still use every character exactly.

If a reply is lost and a retry gets 306, the extension reads the record again. It counts success only if the intended values already match. Different number formats are accepted only for fields known to be numbers. Text, dates and timestamps must match exactly, including spaces and leading zeros, apart from line endings; unknown field types use that exact comparison too. If it cannot confirm the result, the row says Could not confirm: the first attempt may have succeeded. Check the record before trying again.

2. Calculated, summary and container fields are read-only

When field details are available, the Record Editor disables calculation, summary and container fields, including repetitions, and leaves them out of Save and Create Record. Use Upload to Container for containers. Batch import skips these columns with warnings, and AI writes refuse them. Remove them from a file intended for import; related columns also are not a way to create related records. Global fields remain editable and say Session-wide. FileMaker still decides your account's field privileges. If field details cannot be read, the editor warns that it cannot identify read-only fields; check before saving. A failed Create Record field lookup shows an error; select another layout and then the intended layout again to retry.

3. Empty searches offer List records instead

An empty Query Builder form, [] or [{}] sends no find. Choose List records instead to list the current layout with the current page size, starting record and sort. Nothing is listed until you choose it. This needs a direct connection; a proxy connection asks you to enter criteria. Saved queries, batch exports, AI searches, generated clients and copied code still refuse empty searches. To find an empty field, use is empty, which supplies =.

4. CSV exports carry record versions and preserve text

The first two columns are recordId and modId. If those clash with layout fields, the record columns become __recordId and __modId, with more underscores if needed. Keep them first and together; do not edit their values. An older ambiguous file is refused: export again. Fields missing from the first record are included too. Imports and the Record Editor keep number-looking text, leading zeros and spaces instead of guessing its type. Number fields receive numbers only for safe decimal values; other entries stay text with a warning, so large numbers are not rounded. Empty CSV cells still leave a field unchanged. Duplicate column names are refused, and unsupported import formats explain which file to use.

Excel-compatible CSV (UTF-8 BOM) adds the encoding marker Excel needs. The formula-safety setting is unchanged and still defaults to on. Failed or cancelled exports leave an existing destination file alone. The final __portalNote (export information) column appears only when related rows are truncated; import ignores it. Keep it last or remove it. A CSV export does not contain complete related records when that note is present. The Record Viewer can Load more portal rows on a direct connection and retry a failed load; proxy portal paging and creating related rows remain unsupported.

5. Trusted fingerprints work with VS Code's default proxy setting

A trusted certificate fingerprint now works on a direct connection with every http.proxySupport value, including the default override. You no longer need to change that setting just to trust FileMaker Server's default certificate. The fingerprint is checked before credentials are sent; a changed certificate is refused even if a public authority trusts it. A trusted fingerprint takes priority over a CA file or the older Allow self-signed flag.

A pinned connection that needs an environment, VS Code or system/PAC proxy is refused with PIN_THROUGH_PROXY. Exclude the server from the proxy, or add it to NO_PROXY for an environment proxy if your network permits a direct connection. For a certificate with proper server names, you can instead forget the fingerprint and use the company CA file. CA-only profiles keep their existing certificate handling and proxy routing.

Older Allow self-signed profiles go direct unless an environment proxy applies. Behind that proxy their previous route remains, and VS Code may still replace their certificate handling. http.proxySupport does not disable an environment proxy. Failures that identify the proxy now say the proxy could not be reached and name the relevant settings. Advice to try fallback is limited to older certificate handling on that route, not CA-only failures. Prefer trusting a confirmed fingerprint or a public certificate to the older flag, which skips certificate checks when applied.

The wizard clears the trusted fingerprint when you change the server address, explains when a saved password can be kept, and offers Save anyway after a failed test. Certificate advice now distinguishes date problems, missing intermediates and Data API failures.

6. Test My Server and Diagnose Connection

FileMaker: Test My Server uses a separate temporary sign-in to read a record and check server behavior. Start with Run read-only test. Scratch-record writes and running a script need separate confirmation and the usual permissions. Use a disposable scratch layout for writes; if cleanup fails the report names the record to remove. The report omits passwords and record values, but review names and server details before sharing it.

FileMaker: Diagnose Connection checks a saved server or an address you type without saving it, signing in or changing trust. It checks the network, certificate and Data API, explains likely fixes, and shows the full fingerprint. Copy Connection Diagnosis for Bug Report offers to hide the server address, port and revealing certificate details. Network probes are direct; the Data API check uses the connection's settings. For proxy profiles this checks the FileMaker server, not the middleware's sign-in. Both commands need offline mode off. No new setting is needed.

One real server was exercised on 2026-10-21, but its FileMaker Server version was not recorded. Its no-match find returned HTTP 200, code 401 and empty data. Other versions may answer differently; any status with code 401 is still treated as no matches. No version has a completed recorded smoke test. See Compatibility.

7. Jobs and the Command Palette

Cancel Job and Show Jobs are always shown, even when power-user mode is off. Cancel stops new requests but waits for sent updates to finish; it does not undo changes. Jobs show changed, failed and untouched records separately and offer Copy failures with error codes. During this session the lists are complete. After restart recent jobs keep all counts and at most 1,000 entries per list, marked when shortened. Copy a full list before restarting if you need it. Cancelled exports say no file was written.

8. Safer edits, files and saved queries

Smaller changes

Rolling back

Use Install Specific Version... in the Extensions view to return to 1.6.0, or install its VSIX if you kept it (only tagged versions have a GitHub release). Profiles and saved data need no migration. Keep an untouched copy of exports before editing them. Version 1.6.0 does not protect batch updates with exported versions and may need the old certificate setting workaround. Installing it does not undo record changes already sent to FileMaker.

Upgrading from 1.5.0 to 1.6.0

This is a minor release. Your profiles, saved queries, settings and stored data carry over unchanged, and no command or setting was removed or renamed. Nothing needs to be done for a normal install. These are the behavior changes you may notice.

1. Fields look the same everywhere, and Layout Mode can tidy a layout

The find form, Record Editor, Record Viewer and the generated web layout views now use the same field sizes, top labels and responsive spacing as Layout Mode. Your data and layouts are not changed, but these screens will look different from 1.5.0.

Layout Mode adds standard field sizes and spacing, an action that arranges the selected objects into a standard form, an action that standardizes them, and starter templates (blank, form, two-column, first portal; the templates are offered for a new, empty web layout). Arranging and standardizing each undo in one step. Nothing is rearranged until you choose an action; field names and behavior bindings stay as they are. Layout Mode now lists fields in FileMaker's field order instead of alphabetically.

Apps you generated before: the next time you run Generate FM Web Next.js App or Start FM Web Preview Server, the extension refreshes the managed runtime files in an app you generated earlier (template version 2 becomes 3: page.tsx, bridge-client.ts, runtime-data.ts, runtime-behavior.ts and runtime-layout-client.tsx). A managed file you edited is not overwritten: a warning names it, and you delete that file and run the command again to get a fresh copy; until then the preview cannot reach the bridge.

2. Trusting a certificate can need one VS Code setting

If you trust a server's certificate by its fingerprint (for example FileMaker Server's default certificate), the extension checks that one certificate itself. VS Code's http.proxySupport setting at its default, override, replaces the extension's own connection for servers that are not on your computer, so the trust cannot take effect and the normal certificate check applies instead. Before this release that ended in a misleading "not trusted" message right after you trusted the certificate.

In 1.7.0 this setting change is no longer needed for direct connections; see the 1.7.0 notes above.

Smaller changes

Rolling back

Install the previous version from the Extensions view (Install Specific Version...) or from a release (only tagged versions have one). Your data is not migrated, so nothing needs to be undone.

Upgrading from 1.4.0 to 1.5.0

This is a minor release. Your profiles, saved queries, settings and stored data carry over unchanged, and no command or setting was removed or renamed. Nothing needs to be done for a normal install. These are the behavior changes you may notice.

1. Scripts run with a single request, and return only the script's answer

The extension now runs a script the way the Claris Data API Guide documents it: one GET .../layouts/<layout>/script/<script>?script.param=<text>. Before, it sent a POST that the Data API does not accept and then fell back to a find with the script attached, so every script run also read a record.

2. Names are no longer trimmed

Layout, script and field names are now used exactly as the server lists them or as you typed them. A name with a leading or trailing space (for example Sales) used to be turned into Sales, which could not be opened or, worse, pointed at a different layout. Layouts that differ only in spacing or case are now separate entries. Action: if you have a saved query, a generated type file or a snippet that was created for a layout whose name begins or ends with a space, check it still points where you expect. Names without such spaces are not affected.

3. @filemaker in the Chat view (new, off until you switch AI tools on)

VS Code's Chat view now lists a read-only @filemaker participant (/layouts, /describe, /find, /explain, /help). It reads the database only through the AI tools, so it does nothing until you turn those on (filemaker.ai.enabled and a connection chosen with Set AI Access for Connection; both are off by default), and it follows every AI setting, approval, limit, hidden-field rule and the kill switch. It has no command that changes a record or runs a script, even if you allowed writes and scripts for agent mode. In an untrusted workspace (Restricted Mode) it is listed but answers every request with "AI tools are not available right now" and reads nothing. It sends the language model only layout and field names and your own words, never record values or connection details. There is no new setting. See Chat with @filemaker.

4. Copy a request as code

Copy request in the Query Builder and Script Runner now offers curl, fetch(), a .http file (for the REST Client extension), a Postman collection and TypeScript, and the Record Viewer and Record Editor have Copy request for this record. A new command, FileMaker: Copy Request as Code…, copies a request for the active connection. Your password, session token and API key are never copied. The existing setting filemaker.snippets.includeAuthByDefault (default off) now covers all of these: with it on, copied requests show an Authorization header with a variable to fill in (for example $FM_TOKEN) instead of <REDACTED>. See Copy a request as code.

Smaller changes

Rolling back

Install the previous version from the Extensions view (Install Specific Version...) or from a release (only tagged versions have one). Your data is not migrated, so nothing needs to be undone.

Upgrading from 1.3.0 to 1.4.0

This is a minor release. Your profiles, saved queries, settings and stored data carry over unchanged, and no command or setting was removed. Nothing needs to be done for a normal install. These are the behavior changes you may notice, and what to do about each.

1. A repository file can no longer grant a role or switch protections off

A workspace .vscode/settings.json or .vscode/filemaker.config.json can make the extension stricter. It can no longer loosen anything you set in your own user settings:

Setting or file A workspace can still A workspace can no longer
filemaker.enterprise.mode, enterpriseMode in filemaker.config.json turn enterprise mode on turn it off
filemaker.enterprise.role, role in filemaker.config.json lower the role raise it above your own user setting (default developer)
filemaker.offline.mode turn offline mode on turn it off
filemaker.features.*.enabled turn a feature off turn a feature on

Action: if you relied on a repository file to grant admin, to switch enterprise mode off or to switch a feature back on, set it in your user settings instead. filemaker.secrets.fallback and filemaker.export.neutralizeFormulas are read from user settings only too, and several settings are ignored in an untrusted workspace (see the settings reference).

Toggle Offline Mode now changes your user setting and reports the mode that is really in effect. A workspace offline.mode: true written by an older version stays on and the command says so; edit that workspace setting yourself.

2. Generated file names with spaces or punctuation have a hash suffix

A layout whose name has anything besides letters, digits, _, . and - now gets <safe name>-<8 characters>.ts under <typegen output>/layouts/. Layouts that used to collide on one file now get separate files. Action: regenerate, update imports, and delete the old generated files. Names are also escaped inside the generated code. Layout names containing .. (for example Q1..Q2) work in snapshots and the offline cache.

3. CSV and Copy as table apostrophes

CSV exports (batch export and Query Builder) and Copy results as table put a leading apostrophe in front of text that starts with =, +, -, @, a tab or a carriage return, for example '=SUM(A1). Plain numbers and phone numbers are not changed. Action: if another program reads these files, strip a leading apostrophe there, or set filemaker.export.neutralizeFormulas to false in your user settings (JSON Lines exports never had it). Batch update skips the recordId and modId columns, so a CSV export of a layout with plain fields can be edited and imported back. Exports also contain related (Table::Field), calculation, summary and container columns, and import sends every column back: delete those columns before importing, and do not expect an export to restore old values for layouts that have them.

4. New prompts

You will now be asked before:

5. AI features are off by default

New commands (Write AI Context, Set AI Access for Connection, Show AI Activity, Start New AI Session, Switch AI Tools Off or On, Start/Stop AI Server for External Tools, Copy MCP Config for Claude Code / Cursor) and filemaker.ai.* settings. Profiles gain an optional aiAccess (none by default), which resets to none if you change the profile's server, user, database or API paths. Nothing is read by an AI tool until you set filemaker.ai.enabled in your user settings and choose a connection. A status bar item AI: off is shown on the right; selecting it explains why AI is unavailable, or asks before switching tools back on if you used the kill switch. Older extension versions drop the unknown ai entry from disabledFeatures; use filemaker.features.ai.enabled in the same files if a team still has older versions.

6. Create Record works; Delete Record needs the record-edit switches

The Record Editor's create mode lists the layout's fields, has a Create Record button and a confirmation, and shows the new record's ID. Editing, creating, deleting and uploading, and the Script Runner, now need a trusted workspace. Delete Record now also respects filemaker.features.recordEdit.enabled and the enterprise record-edit restriction, like saving does. Saving a record whose version changed since you loaded it is refused (error 306) and your edits stay in the form.

7. The FM Web live preview is not in the Marketplace build

The Marketplace package does not include the preview app template, so Start FM Web Preview Server and Generate FM Web Next.js App are hidden from the Command Palette (invoked another way they say "not available in this installation") and need the repository. Layout Mode and metadata sync are unchanged. For repository users the preview now sends its bridge token, and previously generated apps get their managed files refreshed (an edited copy is left alone with a warning).

8. Other behavior to know about

Smaller changes

Rolling back

Install the previous version from the Extensions view (Install Specific Version...) or from a release (only tagged versions have one). Your data is not migrated, so nothing needs to be undone, except the renamed generated files (regenerate them) and the aiAccess field (older versions ignore it).

v1.2.0 to v1.3.0

v1.1.0 to v1.2.0

v1.0.0 to v1.1.0

v0.9.0 to v1.0.0

Production release. No breaking changes.

Older versions

For 0.x, see the Changelog.