Troubleshoot the CLI

Start with npx @linguanahq/cli doctor in the app directory. Add --json to any failing command to see its error code. The command reference lists every code and exit status.

Never paste account sessions, build tokens, or the contents of .env.local into support requests. CLI errors already redact token values.

Sign-in

The browser does not open

The CLI could not start a browser. Open the printed address on any device where you can sign in, or run login --no-browser to skip the attempt. Approve the same code shown in your terminal.

LOGIN_EXPIRED: the code expired

Codes expire after ten minutes. Run login again and approve the new code promptly.

ACCESS_DENIED

The request was denied in the browser. If you did not deny it, someone else may have used the code; run login again and approve only codes that match your terminal.

LOGIN_REQUIRED or "Your session has expired or was revoked"

There is no valid session for this API origin. Run login. Sessions are stored per origin: if you use --api-url, or the app's linguana.json points to another API, sign in to that origin. whoami shows the origin of the current session.

INVALID_API_URL

The API origin must be HTTPS, or HTTP on localhost, 127.0.0.1, or [::1]. Pass only the origin, such as https://linguana.example.com, without a path, query, or trailing route.

WRONG_TOKEN_TYPE

LINGUANA_AUTH_TOKEN contains a project build token. That variable accepts only an account session. Unset it to use your saved login.

REMOTE_LOGOUT_FAILED

The local session was removed, but the server could not revoke it. Revoke the session from your account settings when the server is available.

Creating an app

The destination is not empty

create app writes only into a new or empty directory. Choose another directory, or use link to connect an existing app.

INSTALL_FAILED

The app is saved. Make sure the package manager is installed, then run its install command in the app directory. Use --package-manager to choose another package manager next time.

INPUT_REQUIRED in CI

Noninteractive runs need explicit choices: --template, --framework, and --demo or --connect. See Scripts and CI.

Linking a project

FRAMEWORK_REQUIRED or APP_NOT_FOUND

Run the command in the app directory that contains package.json. If the app has dependencies for more than one framework, pass --framework.

INSUFFICIENT_PERMISSIONS

Creating credentials requires Owner or Admin access to an active organization. Ask an owner to change your role, or to run link for you.

SOURCE_LOCALE_MISMATCH

Template apps use English source content. Link them to a project whose source language is English, or create a new project with --new-project.

ENVIRONMENT_NOT_FOUND

The project does not have the requested environment. Projects normally have development, staging, and production. Check the spelling of --environment.

ENV_CONFLICT

The environment file already has different Linguana values or an invalid token. The CLI preserved them. Review the variable names in the message, then retry with --overwrite-env to replace them.

TRACKED_ENV

The environment file is tracked by Git, so the CLI will not write credentials into it. Remove it from the index with git rm --cached .env.local, commit that change, and rotate any token it contained.

SETUP_LOCKED

Another setup is running in this app. Wait for it to finish. If an interrupted setup on another machine left the lock, remove .linguana/cli.lock and retry.

Setup was interrupted

Run link again in the same directory. Setup resumes with the same organization and project and does not create duplicates.

env pull

PROJECT_NOT_LINKED

Run link once first. env pull reads the project from linguana.json.

A new token was created unexpectedly

Token secrets are shown only once. env pull creates a replacement when the local token is missing, revoked, or belongs to another project or environment. Revoke tokens you no longer use in Tokens in the dashboard.

doctor failures

In a Next.js app, the sdk and vite checks always fail because the CLI does not support Next.js yet. Use the Next.js guide to verify the integration.

The app still shows demo or source text

Restart the dev server after linking. Connected templates read your published catalogs and do not use bundled demo translations. Until a language is published to the environment the app reads, it shows English source text.

Next

For build upload errors after linking, see Upload and authentication.