Troubleshoot the Airtable integration
When an Airtable sync is not behaving, start here. Find your symptom in the tables below, confirm the likely cause, and follow the fix. Each row points at the tab where you act and the guide that covers the underlying behavior in depth.
Before you begin
- Open the integration at Apps & Integrations → Airtable. Most fixes happen on the Dashboard, Datasets, Inbound, or Settings tab.
- Check the header status chip first. If it does not read Connected, both outbound and inbound sync are interrupted until you reconnect — fix the connection before chasing anything else.
- Have the connection's account switcher set to the right account if you have connected more than one, so you are reading the correct connection's state.
Connection and authorization
| Symptom | Likely cause | Fix |
|---|---|---|
| The authorization popup never opens, or an error toast asks you to allow popups. | Your browser blocked the popup that opens Airtable's authorization screen, so the connecting spinner stops and nothing is created. | Allow popups for SKU.io in your browser, then select Connect Airtable again. See Connect Airtable. |
| The popup shows Authorization Failed, or a fresh connect ends with an error toast. | Airtable rejected the authorization, or you closed the popup before granting access. A fresh connect that fails during the token exchange is rolled back, so no half-created connection is left behind. | Read Airtable's error message in the toast, then retry from Connect Airtable. Make sure you complete Airtable's Grant access step in the popup. |
| The status chip reads Needs reconnect (amber). | The stored Airtable access token expired or was revoked on Airtable's side. Sync jobs skip any connection that is not Connected. | Select the Reconnect button next to the chip (or on the Settings tab) and complete the Airtable popup. Reconnecting re-authorizes the same connection and keeps every sync mapping. See Connect Airtable. |
| The status chip reads Error (red). | The last connection attempt failed. Unlike a fresh connect, a failed reconnect leaves the existing connection in place. | Select Reconnect to retry the Airtable authorization. If it keeps failing, confirm your Airtable account still grants SKU.io access to the bases you sync. |
| The status chip reads Disconnected (grey) and stays there. | No usable connection resolved — this is also the state shown briefly while the page is still loading. | Wait for the page to finish loading. If it stays Disconnected, connect an account from the Connect your Airtable account empty state. See Connect Airtable. |
| You want to force a re-check of a connection but cannot find a Verify button. | The Settings tab has no verify or recheck button by design — it shows the account email, a status line, and the Disconnect action only. The connection re-verifies on its own before each API call. | Read the status chip and status line on Settings or the Dashboard. To confirm the granted scopes, open the Dashboard tab. To force a re-authorization, use Reconnect. |
Outbound sync
| Symptom | Likely cause | Fix |
|---|---|---|
| A mapping's row on the Datasets list shows a red error chip in Last Sync. | The last run finished with failed rows. SKU.io isolates failures per record, so a few malformed rows do not fail the whole batch — but it holds the sync watermark so those rows retry next run. | Hover the error chip for the count and last error, or open the Activity tab and hover the red error-count chip to read every recorded per-record message. Fix the offending Airtable field or SKU.io data, then run Sync now. See Monitor syncs and connection health. |
| Outbound sync has paused and the Dashboard shows "Monthly Airtable API limit reached — outbound sync is paused until it resets." | The connection hit 100% of its monthly Airtable API cap. Both scheduled runs and real-time pushes stop making calls until the counter resets at the month boundary. This also raises the Airtable Monthly API Cap Reached alert. | Wait for the monthly reset, reduce sync frequency, or turn off Real-time sync on high-volume mappings. You can raise the per-connection cap under the Settings tab. See Reliability, limits, and sync-health alerts. |
| The Dashboard shows an amber "Approaching your monthly Airtable API limit" warning but sync still runs. | Usage crossed 80% of the cap. This is a heads-up, not a pause. | Reduce sync frequency or disable Real-time sync on the busiest mappings before you reach 100%. See Reliability, limits, and sync-health alerts. |
| A Manual only mapping never runs on its own. | Manual only mappings are never swept by the scheduler — they sync only on demand or through real-time push. | Press Sync now on the mapping's row, or set a Schedule other than Manual only. See Sync-mapping settings reference. |
| A mapping does not sync at all, on schedule or in real time. | The mapping is disabled. A disabled mapping is skipped by scheduled sweeps, real-time push, and inbound fetch. | Toggle the Enabled switch on the mapping's row. Confirm Real-time sync is on too if you expect changes to push as they happen. See Sync your data to Airtable. |
| A single SKU.io field never reaches Airtable. | That field is set to Not mapped in the mapping's field grid, or it maps to an Airtable field that another row already claims. | Edit the mapping, open the Fields step, and point the field at an Airtable column. Each Airtable field can be mapped only once. See Sync your data to Airtable and the Dataset and field reference. |
Inbound review
| Symptom | Likely cause | Fix |
|---|---|---|
| Edits you made in Airtable are not showing in the Inbound queue. | Inbound is near-real-time over a webhook, but Airtable's OAuth webhooks lapse after about seven days. When one lapses, inbound falls back to a full-table scan that runs on a fixed every-3-hours schedule — so a recent edit can take up to three hours to appear. This raises the Airtable Webhook Lapsed alert while it heals. | Wait for the next every-3-hours fallback scan, or press Sync now on the inbound mapping to pull changes immediately. Inbound is not broken — the webhook re-registers on its own. See Inbound safety and the field whitelist. |
| An inbound row is stuck with an Unmatched status. | The Airtable key resolved to no SKU.io record and the dataset did not auto-create one. Only Products can auto-create, and only when Create missing products is on; Sales Orders and Suppliers never auto-create. | Correct the key value in Airtable so it matches an existing SKU.io record, or create the SKU.io record first. For products, turn on Create missing products on the mapping if you want unmatched rows created automatically. See Review changes from Airtable. |
| An edit to a field in Airtable is ignored and never appears as a proposed change. | That field is not on the dataset's inbound whitelist. Inbound writes only a short list of descriptive fields and never touches inventory, pricing, costs, dates, or order status — forbidden sources are dropped while the diff is built. | Confirm the field is inbound-writable for that dataset in the Inbound safety and the field whitelist reference. If it is off-limits, edit it in SKU.io instead. |
| An approved inbound change flipped to Failed. | The write could not complete — for example, the SKU.io record was deleted after the change was queued. | Hover the information icon on the Failed row to read the error, then re-create or correct the SKU.io record and re-approve. See Review changes from Airtable. |
| You expected inbound rows but the queue looks empty. | A Status filter is still applied, or the change was unchanged, or the record's key field is blank (blank keys are skipped and never queued). | Clear the Status filter back to All. Confirm the Airtable record's key field has a value and that the edited field is whitelisted. See Review changes from Airtable. |
Still stuck?
- Check the Dashboard for a raised sync-health alert. The three Airtable alerts — Airtable Sync Failed, Airtable Monthly API Cap Reached, and Airtable Webhook Lapsed — each link straight to the screen where you act and clear on their own once the next healthy run happens. See Reliability, limits, and sync-health alerts.
- Remember that datetime values written to Airtable are in UTC, so an Airtable column can differ from the app-timezone display in SKU.io. That is expected, not a sync fault. See the Dataset and field reference.
Next steps
- Connect Airtable — reconnect or disconnect a connection that needs re-authorization.
- Monitor syncs and connection health — read run results, error messages, and the API-usage meter.
- Reliability, limits, and sync-health alerts — how the cap, rate limits, and the three alerts behave.
- Review changes from Airtable — resolve unmatched, pending, and failed inbound rows.
- Inbound safety and the field whitelist — exactly which fields each dataset can write back.
- Sync-mapping settings reference — schedule, delete mode, apply mode, and the save-time guardrails.
Last verified:
Was this helpful?