CLI

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.

6 min readUpdated DocumentationEdit this page
On this page13

Start with the two quick checks:

Terminal
❯axil --version # expect @axiljs/cli v0.3.6
❯axil doctor # Node.js, TypeScript, project files, @axiljs/core, lock file, .env in .gitignore

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/cli is installed globally, npx may 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:

❯npm install
❯pnpm install
❯yarn install
❯bun install

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.

Terminal
❯npm install -g @axiljs/cli
❯axil --version

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

Output
TXT
  → Studio skipped  @axiljs/studio not installed: npm install -D @axiljs/studio

axil 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:

❯npm install -D @axiljs/studio
❯npm run dev
❯pnpm add -D @axiljs/studio
❯pnpm run dev
❯yarn add -D @axiljs/studio
❯yarn run dev
❯bun add -d @axiljs/studio
❯bun run dev

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:

PowerShell
attrib -h -s .\deploy\*.*

or, for a single file in PowerShell:

PowerShell
(Get-Item .\axil.scaling.json -Force).Attributes = 'Normal'

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 --yes there 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

MessageFix
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… linesFix 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 1Your 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.ts or *.spec.ts (or .js) and live under src/ or tests/. Custom projects start without tests; templates ship theirs.
  • Compilation failed / Tests not run: axil test compiles the whole project first; fix the type errors it prints.
  • 0 tests reported although files exist: make sure @axiljs/testing is 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/live and /health/ready. Add both routes to your app, or edit deploy/deployment.yaml.
  • Wrong port: --port defaults to 3000 and does not read .env; pass axil deploy --port 3009 for 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 failed with --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:

Output
TXT
  Unknown flag '--templte'. Did you mean --template? Run 'axil create --help' to see available options.

Run axil <command> --help for the exact options.

Reinstall

Terminal
❯npm uninstall -g @axiljs/cli
❯npm install -g @axiljs/cli@latest
❯axil --version

Reinstalling the global CLI does not touch your projects; each project keeps its own node_modules.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY