NocoDB Schema Troubleshooting
Diagnostics for the dev surface — schema modifications, relations, formulas, views, hooks. For data-side issues see nocodb-ops/skills/troubleshoot.
Quick Diagnostics
- Snapshot the schema.
mcp__nocodb__getTableSchema — confirm the field / view / hook is actually present.
- Check token scope. A 403 from a Meta endpoint usually means the token lacks edit rights on the base, not a bug.
- Verify NocoDB version. Some endpoints (
Links field, Map view, HookV3) are v0.200+. Run curl -sS "$NOCODB_URL/api/v1/health" and check version.
Auth & Permissions
| Code |
Symptom |
Fix |
| 401 |
Token invalid |
Regenerate at NocoDB → Account Settings → API Tokens |
403 on POST /columns |
Token has read-only role on this base |
Switch to a token with editor/creator role |
403 on PATCH /tables/{id} |
Token can edit data but not schema |
Use a higher-privilege token |
| Token works in nocodb-ops but not nocodb-dev |
Wrong env var |
Confirm NOCODB_API_TOKEN (CLI/API) is set, not just NOCODB_MCP_TOKEN |
Field-Type Errors
| Symptom |
Cause |
Fix |
| 422 on field create |
Missing required option for that type |
Check field-types.md for the required keys |
| 422 "type X requires field Y" |
Lookup / Rollup / Barcode / QR missing fk_*_column_id |
Provide the referenced column ID |
| 400 "fk_relation_column_id not found" |
Lookup created before the link field exists |
Create the Links / LinkToAnotherRecord field first |
| Type change rejected (422) |
Incompatible existing values |
Audit and clean values; or recreate the field with the desired type and migrate data |
MultiSelect → SingleSelect rejected |
At least one record has multiple values |
Reduce records to one value each before changing |
LongText → Number rejected |
Non-numeric existing values |
Set those values to null or numeric first |
| New SingleSelect option not visible |
UI cache |
Hard-refresh; the API call succeeded |
Relation Errors
| Symptom |
Cause |
Fix |
| Inverse link missing on the other table |
Links create succeeded but inverse not generated |
Some older NocoDB versions require explicit LinkToAnotherRecord (classic) — re-run with the classic field |
| Lookup column shows nothing |
Underlying link has no records linked |
Verify with GET /api/v3/data/.../links/{linkFieldId}/{recordId} |
| Rollup returns 0 / null |
rollup_function mismatched type (e.g. sum on text) |
Switch to count or countNotEmpty, or rollup a numeric column |
| Cannot delete table |
Another table has a link pointing here |
Delete that link field first |
| Cycle detected |
Two links forming a self-loop with the same column |
Re-create one side; NocoDB v3 normally allows cycles on different columns |
| Display field of linked table changed |
Display field on the parent was deleted |
Set a new display_field_id on the parent table |
Formula Errors
| Symptom |
Cause |
Fix |
ERR for some rows |
Null operand or type mismatch |
Wrap with IF(ISBLANK({Field}), default, expr) |
ERR for all rows |
Syntax error |
Test the formula on one row in NocoDB UI; common mistakes: smart quotes, missing braces, unsupported function |
| Formula references a renamed field |
NocoDB stores by ID, but visible string uses old name |
Re-edit the Formula; the display refreshes |
| Date arithmetic returns 0 |
Time component truncated |
Use DATETIME_DIFF(NOW(), {Field}, "days"), not naive subtraction |
| String concat wrong |
NocoDB uses & or CONCAT() not + for strings |
Use CONCAT({A}, " ", {B}) |
View Errors
| Symptom |
Cause |
Fix |
| Kanban shows everything in "Uncategorized" |
Records have null group value |
Backfill the SingleSelect column |
| Calendar shows nothing |
Date field null, or filter excludes records |
Inspect view filters; check date population |
| Map renders empty |
Geometry field empty |
Populate Geometry values (POINT format) |
| Gallery cards bare |
No cover image set or attachments missing |
Set fk_cover_image_col_id; upload attachments |
| Form submit error 422 |
Required field missing in payload |
NocoDB form validation lives client-side; for API submits, check field-level constraints |
| View create rejected |
View management requires Enterprise on this instance |
Confirm plan; downgrade to Free-plan operations |
Hook (Webhook) Errors
| Symptom |
Cause |
Fix |
| Hook never fires |
active: false, wrong event, or condition false |
Toggle active; verify event/operation; relax condition |
| Hook fires but destination 401 |
Auth header missing or wrong |
Add Authorization to payload.headers |
{{record.X}} rendered literally |
Wrong column title |
Match exact case-sensitive column title |
| Hook fires twice on bulk-update |
Both insert and update configured on the same hook |
Remove the unused operation from the operation array |
| Email hook never sends |
NocoDB SMTP not configured |
Configure SMTP plugin in NocoDB admin |
Schema Cache & Sync
| Symptom |
Cause |
Fix |
getTableSchema returns stale shape after a write |
Browser-side or MCP cache |
Wait ~30s; hard-refresh; re-call getBaseInfo first |
| Two clients see different schemas |
Active replication lag (self-hosted) |
Confirm replica is up-to-date; pin reads to primary |
| MCP sees a deleted field |
MCP server cache |
Restart MCP, or wait for TTL expiry |
| Field reorder not visible |
Per-view column order overrides table order |
Use view:column:update to reorder per view |
Version Compatibility
| Feature |
Min version |
Links field type (modern) |
v0.200 |
| Map view |
v0.200 |
| HookV3 |
v0.200 |
| Per-view filter groups level 3 |
v0.200 |
display_field_id on TableUpdate |
v0.200 |
Geometry field type |
v0.200 |
Older instances may need LinkToAnotherRecord instead of Links, and the legacy hook v2 schema.
Diagnostic Checklist
When reporting a schema bug:
- NocoDB instance URL and version (
/api/v1/health)
- Plan tier (Free / Self-hosted Enterprise / Cloud Enterprise)
- The exact CLI or API call (with token redacted)
- The full HTTP response body (status + JSON error)
- Output of
mcp__nocodb__getTableSchema for the affected table
- Whether the same operation works in the NocoDB web UI
- Whether the issue is consistent or intermittent
1---2name: troubleshoot-83description: Diagnose schema-side NocoDB errors — read-only fields, type-change rejections, broken Lookups, formula errors, view config validation, version mismatches. Use when: - "field type change rejected" - "Lookup not working" - "formula returns ERR" - "cannot delete table" - "Kanban not grouping" - "schema cache stale" - "NocoDB version too old"4---56# NocoDB Schema Troubleshooting78Diagnostics for the dev surface — schema modifications, relations, formulas, views, hooks. For data-side issues see `nocodb-ops/skills/troubleshoot`.910## Quick Diagnostics11121. **Snapshot the schema.** `mcp__nocodb__getTableSchema` — confirm the field / view / hook is actually present.132. **Check token scope.** A 403 from a Meta endpoint usually means the token lacks edit rights on the base, not a bug.143. **Verify NocoDB version.** Some endpoints (`Links` field, Map view, HookV3) are v0.200+. Run `curl -sS "$NOCODB_URL/api/v1/health"` and check `version`.1516## Auth & Permissions1718| Code | Symptom | Fix |19|------|---------|-----|20| 401 | Token invalid | Regenerate at NocoDB → Account Settings → API Tokens |21| 403 on POST `/columns` | Token has read-only role on this base | Switch to a token with editor/creator role |22| 403 on PATCH `/tables/{id}` | Token can edit data but not schema | Use a higher-privilege token |23| Token works in nocodb-ops but not nocodb-dev | Wrong env var | Confirm `NOCODB_API_TOKEN` (CLI/API) is set, not just `NOCODB_MCP_TOKEN` |2425## Field-Type Errors2627| Symptom | Cause | Fix |28|---------|-------|-----|29| 422 on field create | Missing required option for that type | Check `field-types.md` for the required keys |30| 422 "type X requires field Y" | Lookup / Rollup / Barcode / QR missing `fk_*_column_id` | Provide the referenced column ID |31| 400 "fk_relation_column_id not found" | Lookup created before the link field exists | Create the `Links` / `LinkToAnotherRecord` field first |32| Type change rejected (422) | Incompatible existing values | Audit and clean values; or recreate the field with the desired type and migrate data |33| `MultiSelect → SingleSelect` rejected | At least one record has multiple values | Reduce records to one value each before changing |34| `LongText → Number` rejected | Non-numeric existing values | Set those values to null or numeric first |35| New SingleSelect option not visible | UI cache | Hard-refresh; the API call succeeded |3637## Relation Errors3839| Symptom | Cause | Fix |40|---------|-------|-----|41| Inverse link missing on the other table | `Links` create succeeded but inverse not generated | Some older NocoDB versions require explicit `LinkToAnotherRecord` (classic) — re-run with the classic field |42| Lookup column shows nothing | Underlying link has no records linked | Verify with `GET /api/v3/data/.../links/{linkFieldId}/{recordId}` |43| Rollup returns 0 / null | `rollup_function` mismatched type (e.g. `sum` on text) | Switch to `count` or `countNotEmpty`, or rollup a numeric column |44| Cannot delete table | Another table has a link pointing here | Delete that link field first |45| Cycle detected | Two links forming a self-loop with the same column | Re-create one side; NocoDB v3 normally allows cycles on different columns |46| Display field of linked table changed | Display field on the parent was deleted | Set a new `display_field_id` on the parent table |4748## Formula Errors4950| Symptom | Cause | Fix |51|---------|-------|-----|52| `ERR` for some rows | Null operand or type mismatch | Wrap with `IF(ISBLANK({Field}), default, expr)` |53| `ERR` for all rows | Syntax error | Test the formula on one row in NocoDB UI; common mistakes: smart quotes, missing braces, unsupported function |54| Formula references a renamed field | NocoDB stores by ID, but visible string uses old name | Re-edit the Formula; the display refreshes |55| Date arithmetic returns 0 | Time component truncated | Use `DATETIME_DIFF(NOW(), {Field}, "days")`, not naive subtraction |56| String concat wrong | NocoDB uses `&` or `CONCAT()` not `+` for strings | Use `CONCAT({A}, " ", {B})` |5758## View Errors5960| Symptom | Cause | Fix |61|---------|-------|-----|62| Kanban shows everything in "Uncategorized" | Records have null group value | Backfill the SingleSelect column |63| Calendar shows nothing | Date field null, or filter excludes records | Inspect view filters; check date population |64| Map renders empty | Geometry field empty | Populate `Geometry` values (POINT format) |65| Gallery cards bare | No cover image set or attachments missing | Set `fk_cover_image_col_id`; upload attachments |66| Form submit error 422 | Required field missing in payload | NocoDB form validation lives client-side; for API submits, check field-level constraints |67| View create rejected | View management requires Enterprise on this instance | Confirm plan; downgrade to Free-plan operations |6869## Hook (Webhook) Errors7071| Symptom | Cause | Fix |72|---------|-------|-----|73| Hook never fires | `active: false`, wrong event, or condition false | Toggle active; verify event/operation; relax condition |74| Hook fires but destination 401 | Auth header missing or wrong | Add `Authorization` to `payload.headers` |75| `{{record.X}}` rendered literally | Wrong column title | Match exact case-sensitive column title |76| Hook fires twice on bulk-update | Both `insert` and `update` configured on the same hook | Remove the unused operation from the `operation` array |77| Email hook never sends | NocoDB SMTP not configured | Configure SMTP plugin in NocoDB admin |7879## Schema Cache & Sync8081| Symptom | Cause | Fix |82|---------|-------|-----|83| `getTableSchema` returns stale shape after a write | Browser-side or MCP cache | Wait ~30s; hard-refresh; re-call `getBaseInfo` first |84| Two clients see different schemas | Active replication lag (self-hosted) | Confirm replica is up-to-date; pin reads to primary |85| MCP sees a deleted field | MCP server cache | Restart MCP, or wait for TTL expiry |86| Field reorder not visible | Per-view column order overrides table order | Use `view:column:update` to reorder per view |8788## Version Compatibility8990| Feature | Min version |91|---------|-------------|92| `Links` field type (modern) | v0.200 |93| Map view | v0.200 |94| HookV3 | v0.200 |95| Per-view filter groups level 3 | v0.200 |96| `display_field_id` on TableUpdate | v0.200 |97| `Geometry` field type | v0.200 |9899Older instances may need `LinkToAnotherRecord` instead of `Links`, and the legacy hook v2 schema.100101## Diagnostic Checklist102103When reporting a schema bug:1041051. NocoDB instance URL and version (`/api/v1/health`)1062. Plan tier (Free / Self-hosted Enterprise / Cloud Enterprise)1073. The exact CLI or API call (with token redacted)1084. The full HTTP response body (status + JSON error)1095. Output of `mcp__nocodb__getTableSchema` for the affected table1106. Whether the same operation works in the NocoDB web UI1117. Whether the issue is consistent or intermittent
agents-store