Status and troubleshooting

Start with the read-only status report:

npx @microfeed/cli manage status

When several sites are saved, add the exact --instance <name>.

Read the final recovery message before trying a different command. The management CLI is designed to resume interrupted work; creating or deleting a similarly named resource by hand can make recovery harder.

The wrong Cloudflare account appears

Run npx @microfeed/cli manage accounts. If you intentionally need another named Wrangler login, select or create it with --profile <name>; use --reauthorize only when you deliberately want fresh browser authorization. If several accounts are listed, choose by name and full ID rather than position.

A Worker already uses the requested name

Initialization will not overwrite an unknown Worker. If it is an existing microfeed site, use the printed npx @microfeed/cli manage connect --worker ... --instance ... command. Otherwise choose a different, distinctive project name.

A new Cloudflare account cannot serve workers.dev yet

Cloudflare may take a few minutes to prepare the first Workers subdomain. Wait, then rerun the same npx @microfeed/cli manage init command. Saved progress resumes the unfinished work.

Media upload is unavailable

Check whether the status report says R2 is ready, pending, or deliberately disabled. Cloudflare may require R2 activation in the correct account. Once it is available, use npx @microfeed/cli manage deploy --enable-r2; do not create an unrelated bucket by hand.

Confirm the dashboard path and authentication state in the status report. Use npx @microfeed/cli manage auth reset-password for built-in login. If Cloudflare Access is also enabled, test each layer and logout flow in a private browser window.

The dashboard saves, but public content is missing

Check the channel’s Site access setting, the item’s visibility, and the exact public hostname. Then inspect /, /rss/, and /json/. An offline channel intentionally returns not-found responses for all non-admin routes.

API routes return 404 or 401

A 404 usually means API access is disabled, or public API docs are not published for a documentation URL. Check API → API Settings in the dashboard. A 401 on an integration endpoint means the request did not send a currently active API key as Authorization: Bearer <api-key>. If a key was rotated or revoked, update the integration immediately.

Webhook deliveries fail or stop

Open Admin → Webhooks → Deliveries to inspect the status, attempts, response diagnostics, and suppression reason. Then run npx @microfeed/cli manage status to check the saved infrastructure state. Enabled webhooks require the exact Queue, producer binding, Worker consumer, resumed delivery, and hourly Cron. Disabled webhooks require the retained Queue to be paused and empty with no binding, consumer, or Cron. Do not rotate a signing secret or redeliver an event until you know which receiver configuration and deployed environment are active.

If disabling or re-enabling was interrupted, rerun the same npx @microfeed/cli manage deploy --disable-webhooks or --enable-webhooks command for the exact instance and environment. The operation resumes from saved progress. Do not create, rename, resume, purge, or delete a similarly named Queue by hand; an unexpected Queue ID fails closed to protect another resource.

Use Operate and troubleshoot webhooks for response handling, retries, budget suppression, auto-pause recovery, signing-secret rotation, and safe manual redelivery.

Before reporting a bug

Include the failing command, non-secret error text, operating system, and microfeed source commit. Say what you expected and what happened instead. Remove emails, account IDs, private dashboard URLs, tokens, and content that should not be public.