Every error the CLI prints is followed by its code and a link to its entry here, like VQ101 · https://www.valiqai.com/docs/cli-troubleshooting#vq101-no-api-key. With --json, the code is in the output's code field. valiqai doctor checks the usual causes in one go.

VQ101 No API key

No API key. Run valiqai login, or set VALIQAI_API_KEY to a ValiqAI API key (Settings › API keys, or Team settings › API keys).

The CLI found no key. On your computer, run valiqai login. In CI, check the secret is named VALIQAI_API_KEY and is passed to the step as an environment variable.

VQ102 Not signed in to that workspace

You aren't signed in to a workspace called "…". Run valiqai login to add it.

--workspace, VALIQAI_WORKSPACE or valiqai.json names a workspace you haven't signed in to on this computer. Run valiqai login and pick it, or check the name with valiqai switch.

The sign-in request expired before it was approved. Run valiqai login again.

A sign-in request lasts 10 minutes. Run valiqai login again and approve it in the browser.

The sign-in was denied in the browser.

Someone pressed Deny on the approve page. Nothing was created. Run valiqai login again if that was a mistake.

Sign-in failed (HTTP …).

ValiqAI refused the sign-in for a reason the CLI doesn't know. Run valiqai login again; if it keeps failing, sign in with a key you make under API keys: valiqai login --key <key>.

VQ106 Only owners and admins can add the CLI to a team

Only owners and admins can add the CLI to this team

Shown on the approve page next to a team you can only view. Ask a team owner or admin to sign the CLI in to the team, or pick another workspace. Shown on the approve page, not in the terminal.

VQ107 The key was refused

Login failed: …

valiqai login --key checked the key with ValiqAI and it was refused; the reason follows the colon. Copy the key again, or make a new one under API keys.

VQ108 Can't reach ValiqAI

Couldn't reach ValiqAI at …: …

The request never got an answer: no network, a proxy or firewall in the way, or a wrong --api-url / VALIQAI_API_URL. valiqai doctor checks the address. In CI, the runner needs outbound HTTPS to www.valiqai.com.

VQ109 The key can't do that

This key doesn’t have the scope for that. Sign in again with valiqai login, or make a key with it under API keys.

The key is missing the permission this needs (ValiqAI answers "Insufficient permissions"). scan needs Start scans, results need Read results, and valiqai domains needs Manage your domains, which only personal keys have. A key from valiqai login before 1.6.0 can't manage domains: run valiqai login again.

VQ110 Pick a workspace

Signed in to: …. Run valiqai switch <workspace>.

valiqai switch with no workspace asks which one, which needs a terminal. Name it instead: valiqai switch acme.

VQ201 No URL to scan

No URL to scan. Pass one, like valiqai scan https://staging.example.com, or run valiqai link in this folder.

There's no URL on the command line and no valiqai.json here or in a folder above. Pass the address, or run valiqai link.

VQ202 Not a URL

Not a URL: …

Pass a full address with https://, like https://staging.example.com.

VQ203 Unknown --fail-on

--fail-on must be blocker, major, minor or none (got "…").

Use blocker, high (or major), medium (or minor), or none. The same goes for scan.failOn in valiqai.json.

VQ204 Unknown --timeout

--timeout must be a duration like 15m, 900s or 1h (got "…").

Give a number with s, m or h, like 20m. A plain number is seconds.

VQ205 Unknown --on-timeout

--on-timeout must be cancel or keep (got "…").

cancel stops a scan still running at --timeout; keep leaves it running in ValiqAI.

VQ206 Unknown --type

--type must be e2e or security (got "…").

Use e2e or security. The same goes for scan.type in valiqai.json.

VQ207 Unknown --format

--format must be json, junit, sarif or markdown (got "…").

See Reports for what each format is for.

VQ208 Can't tell the report format

Can't tell the report format from …. Add --format json, junit, sarif or markdown.

--output names a file whose extension isn't .json, .xml, .sarif or .md. Add --format, or rename the file.

VQ209 --json and --format disagree

--json and --format disagree. Use one.

--json is short for --format json. Drop one of them.

VQ210 --output needs a format

--output needs a report format. Add --format json, junit, sarif or markdown.

--format text is the progress log, which has no file to write. Pick a report format.

VQ211 --no-wait has no result

--no-wait has no result to report as …. Use --format json, or drop --no-wait.

With --no-wait the CLI exits before the scan finishes, so there's nothing for JUnit, SARIF or Markdown to hold. --format json still prints the scan's id and link.

VQ212 ValiqAI refused the scan

Couldn't start the scan (HTTP …): …

ValiqAI said no; the reason follows the colon. When it's one listed here (an unverified domain, credits, the key), the CLI shows that one's code instead. These are never retried.

VQ213 ValiqAI failed to start the scan

ValiqAI couldn't start the scan (HTTP …): …

Something went wrong on our side. Run the job again; if it keeps happening, tell us with the time it happened.

VQ214 Waited too long to start

Couldn't start the scan within … (--timeout): …

A workspace runs one scan at a time. scan waited for the scan already running (the log names it), and it was still going at --timeout. Let it finish, or stop it with valiqai scans cancel, then run the job again. If your pipelines often overlap, give them a longer --timeout.

VQ301 --env needs valiqai.json

--env needs a valiqai.json here. Run valiqai link first.

--env picks an address from valiqai.json, and there isn't one in this folder or above. Run valiqai link, or pass the URL.

VQ302 valiqai.json has a problem

…: …

The file isn't valid; the problem names the field and what it should be. Fix it, or run valiqai link to write it again. Editors that read its $schema line point at mistakes as you type.

VQ303 No such environment

valiqai.json has no "…" environment. It has: ….

--env names an address that isn't in valiqai.json. Use one it lists, or add it to the file's environments.

VQ304 No verified domains yet

No verified domains in … yet.

valiqai link ties a folder to a verified domain. Verify one first: valiqai domains add example.com --wait, or see Verify your domain.

VQ305 Address isn't under the site

… … isn't under ….

Every address in valiqai.json must be the site or one of its subdomains, since that's what its verification covers.

VQ306 Couldn't read the workspace

Couldn't read your workspace: …

valiqai link asks ValiqAI for the workspace and its domains. Check valiqai whoami, then try again.

VQ401 Can't read the scan

Couldn't read the scan (HTTP …): …. Does the key have the "read" scope?

The scan started, but the key can't read results. Create a key with both Start scans and Read results.

VQ402 Lost contact while waiting

Lost contact with ValiqAI while waiting (5 failed checks in a row). The scan may still finish: …

Five checks in a row failed (the network, or ValiqAI). The scan itself may be fine: open the link, or follow it with valiqai scans watch <id>.

VQ403 Stopped at --timeout

Still running after … (--timeout). Stopped it, so it doesn't hold the workspace: …

The scan took longer than --timeout, so the CLI stopped it and released its unused credits. Give big sites more time, like --timeout 30m, or add --on-timeout keep to let it finish in ValiqAI without waiting for it.

VQ404 Still running at --timeout

Still running after … (--timeout). It keeps going; see …

The CLI stopped waiting, as --on-timeout keep (or scans watch) asks, and the scan carries on. Its result shows in ValiqAI when it ends.

VQ405 Couldn't stop it at --timeout

Still running after … (--timeout), and it couldn't be stopped. It keeps going; see …

The CLI tried to stop the scan and ValiqAI didn't confirm it. Stop it from its page, or with valiqai scans cancel <id>.

VQ406 The scan couldn't finish

The scan couldn't finish (…).

The scan errored or was stopped before it finished, so there's no verdict. Its page says what happened. Run it again; if it keeps failing on the same step, tell us.

VQ407 No such scan

No scan … that this key can see.

The id is wrong, or the scan belongs to another workspace. A team key sees its team's scans; a personal key, the ones you started. Check the id with valiqai scans, or pass --workspace.

VQ501 Not one of your domains

… isn't one of your domains. See them with valiqai domains, or add it with valiqai domains add ….

valiqai domains verify, remove and open work on domains you've added. Add it first.

VQ502 Not verified yet

… isn't verified yet. Check the record, then run valiqai domains verify ….

The TXT record wasn't found before --wait gave up. Check its name and value with valiqai domains verify, which prints them. Most records show up within minutes; some providers take up to 48 hours.

VQ503 Removing needs --yes

Removing … needs --yes when nobody can answer the question.

valiqai domains remove asks first, which needs a terminal. In a script, add --yes.

VQ701 Invalid API key

Invalid API key

The key is wrong or was deleted. Copy it again, or create a new one. Check there are no spaces or line breaks around it in your secret.

VQ702 API key expired

API key has expired

Create a new key under Settings › API keys and update your secret. On your computer, valiqai login makes a new one.

VQ703 Plan without API access

API access requires an upgraded plan

API keys only work on plans with API access. For a team key, the message is "API access isn't on this team's plan".

VQ704 Domain not verified

Domain not verified. Add "…" to your verified domains before scanning.

The site's domain isn't verified in the account the key belongs to. Verify it with valiqai domains add <domain> --wait, or see Verify your domain.

VQ705 Another scan is running

This workspace already has … in flight (cap …). Wait for it to finish or stop it.

scan waits for this on its own, up to --timeout, and only fails with it when the other scan is still running then. See VQ214.

VQ706 Not enough credits

This … reserves … credits. You have … available.

Buy credits in ValiqAI (valiqai credits prints the link), or turn on auto-refill. A scan gives back what it doesn't use when it finishes. Never retried.

VQ707 Team keys can't change domains

A team key can’t change domains; they belong to a person. Use a personal key or valiqai login.

Domains are verified per person. Sign in to your personal workspace with valiqai login, or use a personal key with Manage your domains.

VQ708 Checked too soon

Please wait …s before checking again.

ValiqAI looks for a TXT record at most once every 30 seconds per domain. valiqai domains verify --wait waits for you.

VQ709 Which workspace?

create or select a workspace

A personal key whose owner is in several workspaces doesn't say which one to bill. Use valiqai login and pick one, or a team key in CI.

VQ710 The key's monthly limit is used up

This key's monthly limit (…) is used up. Raise the limit under API keys, or wait for next month.

The key was made with a monthly credit limit, and its scans have used it (or this one would go over it: "This scan would go over this key's monthly limit…"). Someone who manages the key can raise the limit under API keys; it resets on the 1st (UTC). The workspace's own credits are untouched.

VQ711 The site is behind protection

… …. ValiqAI can't scan sites behind protection yet, so nothing was started or charged. Scan an address without it, like a preview with protection turned off.

Before a scan starts, ValiqAI checks whether the address answers with HTTP basic auth, Vercel Deployment Protection, Cloudflare Access or Netlify password protection. A scan of it would only test that wall, so it's refused and no credits are held. Scanning through protection (bypass tokens, basic auth, headers and cookies) isn't available yet; scan a deployment without it for now. See Protected staging sites.

VQ801 Unknown setting

Unknown setting: …

valiqai config list shows the settings: apiKey, apiUrl, defaultMode and timeout.

VQ802 Setting can't be changed

Can't set "…".

Keys are saved by valiqai login, not config set.

VQ803 Not a valid value

"…" isn't a valid …: ….

The message says what the setting takes.

VQ804 The workflow already exists

… already exists. Run with --force to replace it.

valiqai init never overwrites a workflow. Add --force to replace it, or edit it yourself.

VQ805 Unknown shell

Pick one of: bash, zsh, fish, powershell (got "…").

valiqai completion prints a script for bash, zsh, fish or PowerShell. See Shell completion.

VQ806 Unknown command

Unknown command "…".

valiqai --help lists every command. A close match is suggested when there is one.

VQ901 Security scan runs as End-to-End

Chatbot security scans are not available yet; this runs as an End-to-End scan.

You asked for --type security, and chatbot scans aren't open yet. The scan runs as End-to-End and is charged as one. Nothing to fix; drop --type security to stop seeing it.

Without --chatbot-consent, ValiqAI finds your chatbot but sends it no attack prompts.

A security scan needs your say-so before it attacks a chatbot. Add --chatbot-consent if you're allowed to security-test it.