Frontend

Troubleshooting

The errors and warnings the CLI and the frontend server print most often, what causes them, and how to fix them.

Every failure the CLI prints names its fix on a line starting with →. This page collects the common ones, with what causes them. Add --verbose to any command to stream the full pnpm and Vite output and the stack trace of the underlying error.

The backend

No backend URL and no running project

✖ No backend URL provided and no running antelope project found
  Searched for .antelope/dev.json from the current directory upward.
  → Run this command inside an antelope project started with 'ajs project dev'
  → Or pass the backend explicitly with -b <url> (env: DMS_API_BASE_URL)

ajs dms dev looks for the .antelope/dev.json a running ajs project dev writes, from the current directory upward. Start the backend first, run the command from inside the project, or pass -b.

Backend URL is required

✖ Backend URL is required
  → Pass -b <url> or set DMS_API_BASE_URL

build and start never discover the backend. Set DMS_API_BASE_URL in the environment or the .env of the directory you run them from.

Invalid backend URL

✖ Invalid backend URL 'localhost:5010'
  → Include the scheme: -b http://localhost:5010

The URL needs its http:// or https:// scheme.

Cannot reach the backend

▲ Skipped prepare: Cannot reach the DMS backend at http://localhost:5999
  Connection refused (ECONNREFUSED).
  → Start the backend (`ajs project dev` for a local one), or pass its URL with -b <url>

dev and prepare fall back to the cached manifest when the workspace has one; build exits 1 unless you pass --offline. See Workspaces and cache.

Secrets

DMS_SESSION_SECRET is not set, or too short

✖ DMS_SESSION_SECRET is too short: 5 characters, at least 32 needed
  build and start sign sessions with it, so it must stay the same across restarts.
  → Create one: openssl rand -hex 32, then set it in the environment or ./.env

build and start need the same secret, 32 characters or more. dev generates one only when the variable is not set at all.

▲ DMS_HTML_RENDER_SECRET is not set: e-mail renders will be refused
▲ DMS_OAUTH_RELAY_SECRET is not set: OAuth sign-in will be refused by the backend
  → Set them, or rebuild with DMS_BOOTSTRAP_SECRET so the manifest carries them

The build was made without the backend's bootstrap credential, so its manifest carries none of the secrets the backend publishes. Rebuild with DMS_BOOTSTRAP_SECRET set to the backend's frontend.bootstrapSecret. A build made that way also misses the modules' private options and the backend proxies the manifest declares: a module's /ai/** or /media/** calls then fall through to the pages and answer 404.

Builds and modules

A module does not run on this release

✖ These frontend modules do not run on @antelopejs/dms-frontend 0.6.1
  template-dms-demo-frontend-vue (./frontend-vue) supports >=0.5.0 <0.6.0
  → Install a @antelopejs/dms-frontend release in their ranges, or upgrade the modules

A module's engines["@antelopejs/dms-frontend"] excludes the installed loader. Install a loader in the range, using the Compatibility table, or upgrade the module. See Supported releases.

No production build

✖ No production build for https://dms.example.com
  ~/.antelopejs/dms-frontend/842087b6… has no built server or client.
  → Build it first: ajs dms build -b https://dms.example.com

start serves the workspace keyed on the URL it is given. Run build with the same URL, as the same user, on the same machine or image.

A build step fails

The step's error, or the last lines of its output, point at the file in the frontend module rather than at its copy in the workspace. Fix the source and run the command again; --verbose shows every line of every step. When the workspace itself looks broken, remove it with ajs dms clean -b <url> and build again.

The server

The port is busy

✖ Port 3007 is already in use
  → Stop the process listening on it, or pass another port: -p <port>

start stops on a busy port; dev moves to the next free one and says so. -p 0 asks for any free port.

The dashboard is unreachable from another machine

ajs dms dev listens on 127.0.0.1. Set HOST=0.0.0.0 to open it to the network.

start sets Secure cookies, which a browser only sends over HTTPS. Serve it behind TLS, or set DMS_COOKIE_SECURE=false for a plain-HTTP test. Behind several processes, use sticky routing: session refresh is single-flight within one process. See Production.

A backend route answers 404 from the browser

The frontend server only proxies the prefixes the modules declare; everything else is a page, and a write to a page path is a 404. In development, the x-dms-route-owner header names who answered. Declare the prefix with registerBackendProxy, backendProxies or DMS_BACKEND_PROXIES. See Routing and the backend proxy.

Workspaces

The disk fills up

Each workspace takes a few hundred megabytes. ajs dms workspaces lists them with their size and last use; ajs dms clean -b <url> removes one, and ajs dms clean --all every one, after a confirmation. ajs dms dev without -b creates a workspace of its own, keyed on the project: pass -b to share the one build uses.

Security

[object Object]

Modules