Webflow troubleshooting

How publish works on Webflow

A Webflow publish is a two-step API call:

1. Create the collection item. POSTs to the Collection API with your draft fields.
2. Publish the site. POSTs to the Publishing API to push the staged item live.

Most failures happen at step 1 (item creation). Step 2 either succeeds or fails noisily.

"Collection not found"

Caused by:

• Wrong collection ID. The ID is the path segment in the Designer URL, NOT the collection slug. See Connecting Webflow.
• The collection was deleted in Webflow.
• The API token doesn't scope to the site containing that collection.

Fix: re-paste the collection ID from the Webflow Designer URL.

"Field 'X' is required"

The collection has a required field we didn't populate. Open Settings → Integrations → Webflow → Field mapping and map every required field on the collection to a source in your draft.

The most common offenders:

• Required slug field. We auto-generate from the title; if the title contains characters Webflow rejects, the slug fails. Override slug manually before publishing.
• Required custom reference fields (e.g. an "Author" field referencing the Authors collection). Set a default reference value in field mapping.

"Item slug is not unique"

A post with that slug already exists in the collection. The engine generates slugs from titles; identical titles produce identical slugs. Two options:

1. Edit the slug in the publish dialog before clicking publish.
2. Enable Append numeric suffix to duplicate slugs in advanced settings — auto-appends -2, -3 to disambiguate.

"Site publish failed"

Item creation succeeded but the site-wide publish step failed. The item exists in Webflow but isn't live yet.

Causes:

• Site has unsaved Designer changes that block API publish. Open the Designer and publish manually once — future API publishes will work.
• Webflow rate limit. We retry after the rate-limit window; if it persists, lower your publish concurrency in Settings → Integrations → Webflow → Rate limits.

Featured image not attached

Same root causes as WordPress (see WordPress troubleshooting). Specific to Webflow:

• The image field must be of type Image, not Plain Text with a URL. Recheck the collection schema.
• Webflow caches images aggressively. If you replace the image after publish, the new one may take a few minutes to propagate.

Rich text not formatting

Webflow's Rich Text field has its own block model. We convert markdown to Webflow's rich-text JSON before posting. Edge cases:

• Tables. Webflow rich text supports tables; we emit them as native Webflow table blocks. If your collection field is plain rich text without table support, tables render as plain text.
• Code blocks. We emit <pre><code> which renders, but doesn't get syntax highlighting unless your site embeds a highlighter library.
• Embeds. YouTube / Twitter embeds map to Webflow's Embed block. Custom HTML embeds are stripped (Webflow blocks them via the API).

API token rotation

Webflow API tokens don't expire automatically, but you can revoke them. If you rotate the token in Webflow:

• Settings → Integrations → Webflow → Update token.
• Re-test the connection.

We don't re-store credentials silently — you have to confirm the new token.

Multi-site workspaces

A workspace can connect multiple Webflow sites. Each gets its own integration record. When you publish, pick the site from the dropdown in the publish dialog.

What we don't yet support

• Updating existing items. We currently always create new items. Update-in-place is on the roadmap.
• Localized fields. If your collection uses Webflow Localization, we publish to the primary locale only.
• Webflow Ecommerce SKUs. Out of scope for the content engine.