AxilJS CLI Troubleshooting
Fix common axil CLI problems: npx running an old CLI, No matching version after a release, Studio skipped, Windows EPERM, compile errors, tests and deploy.
On this page13
- npx runs an old CLI version
- "No matching version found" right after a release
- axil: command not found
- Studio skipped
- Windows: EPERM when overwriting files
- axil create refuses the name or directory
- axil run problems
- axil test problems
- axil migrate problems
- axil deploy problems
- axil capacity fails
- Unknown command or flag
- Reinstall
Start with the two quick checks:
npx runs an old CLI version
npx @axiljs/cli create can run an older release than the latest, for example a create flow without the template picker. Two usual causes:
-
A cached copy in the npm cache. Ask for the latest release explicitly:
❯npx @axiljs/cli@latest create❯pnpm dlx @axiljs/cli@latest create❯yarn dlx @axiljs/cli@latest create❯bunx @axiljs/cli@latest create -
An old global install. If
@axiljs/cliis installed globally,npxmay use that copy. Update it:Terminal❯npm install -g @axiljs/cli@latest❯axil --version
If it still resolves an old version, clear the npx cache with npm cache clean --force and retry.
"No matching version found" right after a release
Right after a new version is published, npm install (or axil create, which runs it) can fail with No matching version found for @axiljs/...@^0.3.x or ETARGET. The npm registry and its mirrors need a few minutes to propagate a new release. Wait a few minutes and retry:
If the project was created but the install failed, the CLI tells you where it left the directory; delete it and run axil create again, or cd into it and run npm install once the registry has caught up.
axil: command not found
The CLI is not installed globally or the npm global bin directory is not on your PATH.
Restart the terminal after installing (on Windows, close and reopen PowerShell, Command Prompt or Windows Terminal). You can always use npx @axiljs/cli <command> instead, and inside a generated project npx axil <command> uses the project's own CLI.
Studio skipped
→ Studio skipped @axiljs/studio not installed: npm install -D @axiljs/studioaxil run starts Studio only when it can load @axiljs/studio. Projects created with CLI 0.3.3 or later include it as a devDependency; older projects may not:
Studio listens on the app port + 1, where the app port is PORT from .env (default 3000). If something else already uses that port, axil run prints Studio error with the reason and keeps the app running.
Windows: EPERM when overwriting files
On Windows, Node's fs.writeFileSync fails with EPERM: operation not permitted when it overwrites an existing file that has the Hidden attribute (some sync and backup tools set it). This can hit any command that rewrites files, such as axil create --force into an existing folder, axil deploy rewriting deploy/ files, or axil capacity --init --force.
Clear the attribute and run the command again:
or, for a single file in PowerShell:
axil create refuses the name or directory
Directory "my-api" already exists and is not empty. Use --force to create into it anyway.: choose another name or pass--force(files with the same names are overwritten).Project name must be a single directory name, not a path./Only letters, numbers, dots, hyphens, and underscores are allowed.: names cannot contain/or\, and cannot start with.or-.Please provide a project name.: without a terminal (CI, pipes) or with--yesthere is no name prompt.--template rest-api defines its own stack; drop --db/--auth/--ai/--ws/--queue: templates cannot be combined with feature flags.Unknown template "...": the message lists the ten valid ids and suggests the closest one.
axil run problems
| Message | Fix |
|---|---|
No package.json found. / No tsconfig.json found. / No src/ directory found. | Run axil run from the project root |
Initial compilation failed followed by error TS… lines | Fix the errors and save any file; axil run keeps watching and retries |
Could not find entry point (dist/main.js). | tsconfig.json must compile to dist/ (outDir) and the entry must be main.ts, server.ts or index.ts |
Server exited with code 1 | Your app crashed at startup; read the app output above it (often a missing .env value such as JWT_SECRET) |
axil run takes no entry-point argument; it always runs the compiled dist/main.js (or server.js / index.js).
axil test problems
No test files found.: tests must be named*.test.tsor*.spec.ts(or.js) and live undersrc/ortests/. Custom projects start without tests; templates ship theirs.Compilation failed/Tests not run:axil testcompiles the whole project first; fix the type errors it prints.- 0 tests reported although files exist: make sure
@axiljs/testingis installed in the project (npm install -D @axiljs/testing); the tests and the runner must use the same copy.
axil migrate problems
The connection comes from .env: DATABASE_URL for Postgres/MySQL, DATABASE_FILENAME (or DB_FILE) for SQLite, optionally DB_DRIVER. On Node.js older than 22.18, .ts migrations cannot be loaded directly: run npm run build first so dist/migrations is used, or pass --dir=dist/migrations.
axil deploy problems
- Pods never become ready: the manifest probes
/health/liveand/health/ready. Add both routes to your app, or editdeploy/deployment.yaml. - Wrong port:
--portdefaults to 3000 and does not read.env; passaxil deploy --port 3009for an app on 3009. Fix axil.scaling.json or remove it.: the scaling file is invalid; the message names the field. See Configuration.
axil capacity fails
Measurement failedwith--url: the server must already be running and reachable from this machine.- A high failure percentage: the route returned non-2xx responses (often authentication or rate limiting), so the throughput number is not trustworthy. Measure a route that answers 200.
This setup cannot carry the target yet: read the failing checks; each prints its fix. See Capacity.
Unknown command or flag
The CLI suggests the closest match:
Unknown flag '--templte'. Did you mean --template? Run 'axil create --help' to see available options.Run axil <command> --help for the exact options.
Reinstall
Reinstalling the global CLI does not touch your projects; each project keeps its own node_modules.
Was this page helpful?