Draft GitHub Issue — Empty formulaText bug (re-formatted to bug-report.yml form structure)

[doug-hue]

Product

npm package (airtable-user-mcp)

Version

airtable-user-mcp 2.4.10

MCP Client (if applicable)

Claude Desktop

OS

Windows 11

What happened?

download_formula_field and download_base_formulas return empty formulaText for every formula in v2.4.10, even though the formulas exist and are functional in the live Airtable UI. Field metadata (name, IDs, description, resultType) does come back correctly. Sister tool validate_formula works fine.

REPRODUCER

1. Install and authenticate via npx airtable-user-mcp login.
2. Pick any base with at least one formula field.
3. Call download_formula_field against any formula field ID with outputPath omitted:
   { "appId": "appXXXX", "fieldId": "fldYYYY" }

OBSERVED
{
"written": false,
"formulaText": "",
"fieldName": "Performance %",
"tableId": "tbl...",
"description": "",
"resultType": "number"
}

formulaText is empty. Same with download_base_formulas — every .formula file it writes contains only the # AT: header lines, no formula body.

EXPECTED
formulaText should contain the actual formula expression as visible in the Airtable UI's "Customize field type" panel for that formula field.

SAMPLE SIZE
Tested 5 different formulas across 3 tables on a real production base:

• Performance % on Work Orders
• Performance % on Projects
• Performance % on Build Items
• Capacity Bucket on Work Orders
• Can-Start on Work Orders

All five returned formulaText: "". All five formulas are confirmed present and functional in the Airtable UI.

RELATED WORKING TOOL
validate_formula works correctly against the same base and resolves field references against the live schema. The same Patchright session reaches Airtable's internal API for at least some operations.

WORKAROUND
Read the formula via the Airtable UI's "Customize field type" panel directly. No programmatic path currently.

LIKELY CAUSE
Speculation: Airtable's internal API may have renamed or restructured the field in its response payload that holds the formula expression since v2.4.10 was published. The MCP looks for a key that no longer maps, returns empty string.

Relevant logs or errors

# Sample tool invocation and response (formulaText empty as shown):

> Tool: mcp__airtable-user-mcp__download_formula_field
> Args: { "appId": "appKKB4SwDK9cDcSc", "fieldId": "fldkWJhsYODXQuJ81" }
> Response:
{
  "written": false,
  "formulaText": "",
  "fieldName": "Performance %",
  "tableId": "tblFOMNRbxMxetw8T",
  "description": "",
  "resultType": "number"
}

# Same field shows a working formula in the Airtable UI.
# Same behavior with download_base_formulas — 34 .formula files written, all contain only the # AT: header, zero formula body.

[ARHAEEM]

Partial fix on main — defensive fallback chain added; root key needs a capture to confirm.

What changed:

download_formula_field and download_base_formulas both read formula text via a single key path: field.typeOptions?.formulaText. Since resultType (also from typeOptions) comes back correctly but formulaText is empty, the schema response still includes typeOptions — Airtable likely renamed the formula text key within it (or moved it to the field root).

A defensive fallback chain now covers the most plausible alternative locations:

const formulaText = field.typeOptions?.formulaText   // original verified key
  || field.typeOptions?.formula                       // probable rename candidate
  || field.formula                                    // possible field-root move
  || '';

What still needs a capture:

If the actual new key is typeOptions.formula or field.formula, this fallback will already fix the issue once deployed. If Airtable used a different name entirely (e.g. typeOptions.formulaExpression), we'll need to run pnpm capture while opening a formula field in the Airtable UI and inspect the schema response to find the correct key.

Leaving open pending confirmation — if a user on a fresh version confirms download_formula_field now returns formula text, we can close. Otherwise a capture session will identify the exact key and the fallback can be extended.

[doug-hue]

Retested on v2.4.11 (confirmed "version": "2.4.11" in the installed package.json). download_formula_field still returns empty formula text, so the defensive fallback added here doesn't reach the live key.

Repro: called download_formula_field on a real formula field (a percentV2 field whose body is IF(Earned = 0, BLANK(), (Earned - Actual) / Earned)). Response:

{ "written": false, "formulaText": "", "fieldName": "Variance %", "resultType": "number" }

fieldName and resultType come back fine; only formulaText is empty.

Root cause: the live Airtable response stores the formula body under the key formulaTextParsed, which the current fallback chain (field.typeOptions?.formulaText || field.typeOptions?.formula || field.formula || '') never reads. Pulling the same field via get_table_schema shows it under typeOptions.formulaTextParsed. This holds for every formula/rollup field I checked across the base (SUM(values), COUNTA(values), CREATED_TIME(), RECORD_ID(), conditional IF(...) bodies, etc.).

Suggested fix: add formulaTextParsed to the fallback, e.g.

field.typeOptions?.formulaText
  || field.typeOptions?.formulaTextParsed
  || field.typeOptions?.formula
  || field.formula
  || ''

One caveat for the round-trip: formulaTextParsed encodes field references as {column_value_fldXXXX} rather than human-readable names, e.g.

IF({column_value_fldAbc123} = 0, BLANK(), ({column_value_fldAbc123} - {column_value_fldDef456}) / {column_value_fldAbc123})

so a downloaded .formula would contain column-ID placeholders. Still far better than empty, but if update_formula_field expects human field names on upload, those IDs may need translating back (or the upload path may already accept the {column_value_...} form) — worth checking the round-trip.

[ARHAEEM]

Fixed — thank you for the exact key name. The live Airtable internal API stores formula text under typeOptions.formulaTextParsed, which the fallback chain was never reaching.

The chain in both download_formula_field and download_base_formulas now checks formulaTextParsed first:

const formulaText = foundField.typeOptions?.formulaTextParsed   // live key (confirmed)
  || foundField.typeOptions?.formulaText                        // historical fallback
  || foundField.typeOptions?.formula
  || foundField.formula
  || '';

The caveat you noted ({column_value_fldXXX} placeholders for field references) is documented in the code comment. Will ship in the next release.