Troubleshooting

Common issues and their solutions when working with ACMS.

Development Server

”Connection refused” on port 3001

The ACMS dev server is not running. Start it with:

acms dev

Make sure port 3001 is not in use by another process. Use a custom port if needed:

acms dev -p 3002

Fields are not being registered

1. Check the dev server is running — The client needs the dev server at http://localhost:3001 to register fields.
2. Check browser console — Look for network errors to /api/register.
3. Check the server logs — The dev server logs registrations to the console.
4. Verify the field name — displayName and _meta are reserved and cannot be registered.

acms.json is not being created

Make sure you have write permissions to the directory specified in your config. The default path is ./acms.json relative to the project root.

Changes to acms.json are not reflected

1. Check file watcher — The dev server watches acms.json with chokidar. Restart the dev server if the watcher seems stuck.
2. Check your app — Make sure your app is fetching fresh content (not using a stale cache).
3. Check SSE — If using the dashboard, verify the SSE connection is active (check browser DevTools > Network > EventStream).

TypeScript

Types not updating in my editor

1. Make sure acms dev is running — it regenerates acms.d.ts on changes.
2. Restart the TypeScript language server:
   • VS Code: Cmd+Shift+P > “TypeScript: Restart TS Server”
   • Other editors: Restart the LSP
3. Check that acms.d.ts exists in your project root.
4. Verify your tsconfig.json includes the directory containing acms.d.ts.

”Cannot find module ‘@useacms/client’”

Install the client package:

npm install @useacms/client

Type errors for existing fields

If you recently changed the schema, the types might be stale. Regenerate manually:

acms generate-types

Content Sync

acms push fails with authentication error

Check that your adapter credentials are correct:

# Verify environment variables are set
echo $GITHUB_TOKEN
echo $GITHUB_GIST_ID

Make sure the token has the required scopes:

• GitHub Gist: gist scope
• GitHub: repo scope
• Vercel: API token with appropriate permissions

acms pull overwrites local changes

acms pull replaces your local acms.json with the remote version. If you have local changes you want to keep, use acms sync instead for bi-directional merging.

Sync conflicts

When acms sync encounters conflicting values, specify a resolution strategy:

acms sync --resolve local    # Keep local values
acms sync --resolve remote   # Keep remote values

Dashboard

Dashboard shows no fields

1. Make sure the ACMS dev server is running on port 3001.
2. Check that acms.json has content (not just {}).
3. Check the browser console for errors.
4. Verify the dashboard is connecting to the correct port.

Dashboard changes are not saved

1. Check browser DevTools for failed API requests.
2. Make sure the dev server is running and accessible.
3. Check for file permission issues on acms.json.

SSE connection drops

Server-Sent Events connections can drop due to:

• Dev server restart — The dashboard will reconnect automatically.
• Network issues — Refresh the dashboard page.
• Proxy/firewall blocking — Make sure port 3001 is accessible.

Client Library

Content is empty in production

1. Verify you ran acms push to upload content to the production adapter.
2. Check that the production adapter is correctly configured in acms.config.ts.
3. Verify environment variables are set in your production environment.
4. Check adapter-specific issues (e.g., Gist visibility, KV namespace permissions).

Proxy returns undefined

The proxy returns an empty string for unregistered fields in development and undefined for missing fields in production. Check:

1. The field exists in acms.json (or the production adapter).
2. The field path is correct (e.g., acms.hero.title not acms.Hero.Title).
3. The content has been fetched (relevant for runtime strategy).

“displayName” field showing unexpectedly

When a field is migrated from a string to an object (e.g., hero was "Hello" and you access hero.title), the original value is preserved as hero.displayName. This is expected behavior. The displayName field is a reserved internal field.

Performance

Dev server is slow

1. Check if acms.json is very large — consider using acms purge to remove unused fields.
2. Restart the dev server.
3. Check for excessive file watching triggers (e.g., build tools modifying files rapidly).

Too many registration requests

When a page first renders, all accessed fields are registered simultaneously. The dev server uses a promise queue to handle these sequentially. This is normal and only happens during development.

Getting Help

If none of these solutions work:

1. Check the GitHub Issues for known problems.
2. Open a new issue with:
   • Your ACMS version (acms -v)
   • Your framework and version
   • Steps to reproduce
   • Error messages or screenshots