airtable INVALID_FILTER_BY_FORMULA error

TL;DR

INVALIDFILTERBY_FORMULA means Airtable couldn't parse your formula: a syntax slip, a field name it doesn't recognize, or a type mismatch in a comparison. The formula language is picky about quoting and braces. Test the formula in a real Airtable view first; if it fails there too, it's the formula, not the API.

The query

airtable INVALID_FILTER_BY_FORMULA error

Use this when

• Airtable list calls fail with INVALIDFILTERBY_FORMULA
• A formula works in the UI formula field but fails via filterByFormula
• Field renames break a previously working integration

Not for

• Airtable authentication errors
• Airtable rate limits
• Record creation or update errors

Steps

1. Test the formula in an Airtable view

Paste the exact formula into a formula field or a filtered view in the Airtable UI. The UI gives better error messages than the API. If it fails there, fix it there; the API will accept whatever the UI accepts.

Expected output: the formula evaluating correctly in the Airtable UI.

2. Check field names in curly braces

Field references look like {Field Name} with exact spelling, including spaces and casing. After a rename, old references break. Special characters in field names need the braces; without them the parser chokes.

Expected output: every field reference matching a current field name exactly.

3. Fix quoting and types

Text comparisons need single quotes: {Status}='Active'. Numbers compare bare: {Count} greater than 5. Comparing text to a number, or forgetting quotes, both fail. Dates want the ISO string form.

Expected output: the formula's quotes and types matching the field types.

4. URL-encode the formula in the request

The formula travels as a query parameter, so encode it properly. Unencoded braces, quotes, and spaces get mangled in transit and arrive as a different (invalid) formula. Let your HTTP library do the encoding.

Expected output: the exact formula string arriving intact at Airtable.

Variant phrasings

airtable filterbyformula invalid

Steps 2 and 3 cover references and quoting, the two big causes.

airtable formula works in ui not api

Step 4's encoding check; the formula is fine, the transport mangled it.

Why it happens

The formula language looks like a spreadsheet but parses like code, and the API adds a transport layer that the UI doesn't have. So there are two failure surfaces: the formula itself (caught by testing in the UI) and the encoding (caught by comparing what you sent with what arrived). People debug one while the bug is in the other.

Edge cases

• Linked record fields need RECORD_ID() comparisons, not names. Names don't match reliably.
• Empty fields compare oddly: check for BLANK() explicitly instead of =''.
• Very long formulas can hit URL length limits. Prefer views for complex filters.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_XPz7IkPSOuKWXKVgwdsSaw