Troubleshooting

The instance already has an account, so the first-admin setup is finished. Sign in at /login with an existing account. Do not reset the database to fix a sign-in problem. See Troubleshooting for self-hosting.

The token is printed once in the CMS log. With Docker, run docker compose logs cms. If you set SETUP_TOKEN in your environment, use that value instead. See First run.

The CMS address in the browser does not match the configured address. Open the canonical CMS address and check that BETTER_AUTH_URL and APP_URL match it. Restart the CMS after you change either value. See Configuration.

Choose Use a backup code and enter one of the recovery codes you saved when you turned on two-factor authentication. Each code works once. If you have none left, ask another agency admin to help you recover the account. See Two-factor and step-up.

Agency admins must have two-factor authentication turned on. Finish the setup from Account. Do not turn two-factor authentication off on a shared instance. See Two-factor and step-up.

Check that you entered the email address on your account, and check your spam or junk folder. Wait a few minutes before you check again. You can ask for 3 links per hour for each address. If you have asked more than that, wait an hour.

If you sign in with Microsoft or Google, you get a different email. It says how to sign in and has no reset link.

If the page says Ask an agency admin to send you a reset link, ask an agency admin. They can check Agency › Mail, under Recent emails, to see whether the email was sent or why it failed. They can also send you a link from Agency › People. See your account and sign-in.

Your role decides what you can see. Editors write and preview drafts. Owners approve content, go live and manage client members. Agency admins manage Settings and clients. Disabled publish controls explain which role is needed. See Roles and permissions.

Check the address and that the invitation is still pending. Invitations expire after seven days. In the local demo, open the inbox at http://localhost:8025. On a deployed instance, check the SMTP settings. An owner can resend or revoke the invitation. See People and invitations.

The invitation expired, was revoked, or was already used. Ask an owner to send a new one. Also check that you are signed in with the invited email address. See People and invitations.

An entry needs a title that produces a valid, unique slug in its collection before it is saved. Add or edit the title and wait for the save indicator. See Writing entries.

Saving only updates the draft. Mark the entry Ready, then select Go live and wait for the release to finish. The website shows the change only after that release succeeds and the site is rebuilt. If the status shows Edited since ready, the draft has changes that are not ready yet. See Statuses and review and Going live.

The CMS checks required fields, slugs, references, assets, rich text, SEO data and routes before it builds anything. Select each listed item to open the entry and fix the problem, mark the entry ready again, and retry. See Going live.

Each route and slug must produce a unique page on the website. Change the slug of one entry, or change the collection's route, then mark the entry ready again. See Writing entries and Defining content.

A file cannot be deleted while a draft, an approved or scheduled version, an entry's history or a retained release still uses it. Remove the references first. Files in published releases are kept on purpose. See Asset retention.

Reopen the same entry in the same browser. If the CMS has a local recovery copy, it offers to restore it. Review it before you apply it, and compare the entry's history if you need an older version. See Writing entries.

The scheduler starts a release when a scheduled time is due. The scheduled version goes live only when that release succeeds. Check the Go-live panel for a failed release, and check the site's activity for a scheduling failure. After a failure, the CMS retries after about ten minutes. Cancel and reschedule the entry if the schedule is wrong. See Scheduling.

This is expected. A schedule freezes the draft when you set it. Later draft edits do not change it. To publish the newer text, mark the draft ready and schedule it again. See Scheduling.

The site's Production URL must point to a running website that has a preview route. For the local demo site, run the website on port 3001. See Preview and Preview.

Preview links last one hour. Select Preview again from the saved entry to get a new link. Check that your website route passes the whole token through to the SDK. See Preview.

Run areca from the website project root. The CLI reads .env.local and then .env from that folder. Values already set in the shell take precedence over both files. See CLI reference.

areca manifest push needs ARECA_SCHEMA_TOKEN. The read-only site token cannot change the schema. Rotate the schema-write token in Settings › Developer if you do not have it. See Schema sync.

The site token was rotated or copied incorrectly. Rotating a token stops the old one immediately. Update ARECA_SITE_TOKEN in .env.local and in any build secret, then pull again. See Pulling content.

The site has no release yet. A ready entry alone is not enough. Select Go live, wait until the release is live or a demo release is complete, and pull again. See Pulling content.

Run areca pull before your code reads the file, and check that the collection key and output folder match what your code expects. See Pulling content.

Use Node.js 24 LTS, which lets the CLI load areca.config.ts directly. On Node.js 22, see Installation and the CLI reference.

Image URLs come from the CMS address the CMS advertises. Set APP_URL to an address the browser can reach, then make a new release and pull again. Existing releases keep the URLs they were built with. See Configuration.

Mark the SEO changes ready, go live, and rebuild the website from the new release. Check that the website uses the SDK's SEO helpers. See SEO.

Install the version of @tanstack/markdown that the rich text guide names, because the document format changes between versions. See Rich text.

The client has no working deployment connection. Open Agency › Clients › [client] › Deployment, enter the Dokploy URL and API key, and select Save and verify. See Deployments.

Production releases need an application and a health check URL on the site's Settings › Deployment tab. If you only want a local trial, set the mode to Demo. See Deployments and Going live.

Inside a build container, localhost points to the container, not your computer. Use a CMS address the build can reach, and give the build the site token as a build secret. See Deployment targets.

The website's health route must return ok: true and the publication ID of the release it was built from. Check the health URL, TLS and routing, and confirm the build pulled the pinned snapshot. The previous live release stays up. See Go-live builds.

Another build for the same site may be active, or the worker may not be running. Check that WORKER_ENABLED is not set to false, and check the CMS logs for the worker. See Operations.

Check the deployment in Dokploy first, then use Check deployment status on the release in the Go-live panel. Do not start another release until the status is clear, and do not delete job records by hand. See Operations.

Open the Go-live panel and choose Restore this version on an earlier live release. The restore builds that release again. Drafts and ready changes stay as they are. See Going live.

The database, storage, or worker state is unhealthy. Check /api/health/ready for the failing component, then follow the operations checklist. See Operations.

When Redis is unavailable, rate limits count in memory on each instance and the CMS logs a warning. Restore Redis and check the health output. See Rate limits.

The encryption key in the environment no longer matches the key used to save the credential. Restore the original key from your backup, or enter the credential again. Keep encryption keys stable and backed up with the database. See Secrets and Backup and recovery.

AI features need an agency admin to save an OpenRouter key and a model under Agency › AI. The CMS also needs AI_SETTINGS_ENCRYPTION_KEY. A per-user hourly limit applies, and a provider can refuse a request because of model access or credits. See AI settings and AI data handling.