Troubleshooting
CLI errors and exit codes
Every exit code, error code and message the Ulika CLI can print, what causes it in plain words, and how to fix it. Covers connect, init, login, link and Codex.
Last updated
When a CLI command does not finish the way you expected, it tells you why in a sentence and ends with an exit code. This page explains every exit code, every error code, the usage messages, the problems the read-only check can find, and every reason a site can stop while connecting. Start with the exit code (print it with echo $? on macOS and Linux), then find its section.
For how the commands work, see Connect with the CLI and the CLI reference. For the reasons a site can stop in the dashboard, see Connect attention reasons.
Reading a failure#
In a terminal, a failure prints a red cross, the message, and a dimmed hint saying what to do next.
With
--json, a batchconnectends with a line like{"event":"error","code":"...","error":"...","hint":"...","exitCode":11}, and the other commands print one object withok: false,status,code,errorandhint.The exit code is stable. A script can branch on it without parsing English.
Exit codes#
Exit code 0 means success: for connect, at least one site is live and none failed. Every other code is below.
Exit code 1#
An unexpected failure. In ulika status it means ulika.config.json exists but could not be read. In codex install or codex uninstall it means the Codex config could not be updated; the message says why (see Codex). Otherwise the message printed above the code is the cause. If it keeps happening, run the same command with --json and keep the output when you ask for help.
Exit code 2#
A usage error: the command line itself is wrong. It also covers an unknown batch id, a missing project folder, and an address that is not a site. Read the message; the table in Usage messages lists each one with its fix.
Exit code 3#
link: the pairing token does not exist. See token_unknown.
Exit code 4#
link: the pairing token expired. See token_expired.
Exit code 5#
link: the pairing token was already used. See token_used.
Exit code 6#
link: the project the token belongs to no longer exists. See project_missing.
Exit code 7#
The server rejected the request, or the repository does not match. Causes: bad_request, a conflict (see conflict), or a repository mismatch (see repository_mismatch).
Exit code 8#
Protocol mismatch between this CLI and the server. See protocol_mismatch.
Exit code 9#
The server failed while handling the request. See server_error.
Exit code 10#
The server could not be reached, or it answered with something that is not valid. See network and bad_response.
Exit code 11#
Not authorised. See unauthorized, auth_required, invalid_token, denied and expired.
Exit code 12#
This computer's authorisation was revoked. See token_revoked.
Exit code 13#
Forbidden: this account may not do that in that workspace. See forbidden.
Exit code 14#
The scan found no editable content. See empty_scan.
Exit code 15#
init or a local connect <url>: the project was created and its content imported, but the domain is not live yet because the connector pull request still needs a person. Review and merge the connector pull request, or run the same command again with --activate after reviewing it. The message names the next action: preview not verified yet (re-run to resume), preview verified and waiting for activation, or merged and waiting for production. result.nextAction in the JSON says which.
Exit code 16#
init or a local connect <url>: the content was imported, but installing the connector did not finish. The message starts "Content imported, but installation is incomplete" and gives the reason. Fix the reason (it is usually a Vercel or GitHub access problem, branch rules, an untracked file that must be committed, a checkout that is behind the production branch, or a preview that failed to build) and run the same command again; it resumes. The import alone does not turn on publishing.
Exit code 20#
connect: no site went live and none failed, so every site needs a person. This is not an error: the most common reason is that Ulika is waiting for you to merge the connector pull request, which the report links (pull-request-awaiting-merge). The report names each site, the reason in plain words and one next action, for example Open this link and click Activate to put Ulika on your live site. Do that, then run the same command again; it picks the sites up. This code is also what you get when the wait for Activate ends (after 15 minutes by default, or the --wait-timeout you set) when you passed --no-wait, or when the command ran without a terminal (it does not wait there). It also covers a merged site that Ulika is still verifying: nothing is needed from you, run the same command again in a few minutes. Each reason is explained in Attention reasons in the report.
Exit code 21#
connect: at least one site failed. The report lists the failed sites with a reason. See Failure reasons. Failed sites that are transient (a rate limit, a busy host) are retried by Ulika itself before they are reported as failed, so run the command again to retry the rest.
Exit code 22#
connect or login: approval is still required. Either you passed --no-wait (the link was printed and the command stopped on purpose), or nobody approved within 15 minutes ("Nobody approved the request in time."). Open the link that was printed, approve the code, and run the same command again.
A new run collects the same approval instead of printing a new link, as long as the code has not expired.
What you see decides what to do:
"Too many polls for this device code". You are on a CLI older than 0.6.6, which gave up too early on a long wait. Update, then run the command again; current versions ask for a fresh code instead of reusing a dead one.
The page says no installation was found. Install the Ulika GitHub App on the account that owns the repository first, see The approval page.
You type the code into the page yourself. Lower case, a space, or no dash is fine:
abcd efghandABCDEFGHmeanABCD-EFGH.You run the command again. Ulika reuses an open code and opens your browser again.
Exit code 23#
connect with all sites: the list was not confirmed, and nothing was written. In a terminal it means you answered no to Connect these N sites? [y/N]. Without a terminal, or with --json, it is the normal pause: the CLI printed the list (or a confirmation_required line) and waits for a person. Show the list to the person, and if they agree run the same command again with --yes.
Exit code 24#
connect: this agent's site cap is spent. See site_cap.
Exit code 25#
Local connect or init: the repository advertises a different domain than the one you asked for. For example, you asked for acme.com but the repository's own configuration says acme.vercel.app. Nothing was imported. If you meant to associate only the address you gave with that repository, run the command again with --confirm-domain (a terminal asks you instead). If you did not, check the address or choose the right repository.
Exit code 26#
init: "Ulika can't install on <framework> sites yet. It supports React and Next.js. Nothing was created in Ulika." Ulika reads the site's framework right after the scan, and only React (built with Vite and its React plugin, or Create React App) and Next.js (App Router) have an installer today. For a static HTML site, Astro, SvelteKit, Nuxt, Remix, Gatsby, RedwoodJS, Expo or React Native, a React site with another build, or Next.js on the Pages Router, nothing is imported or written: no project, no ulika.config.json, no login or hosting access. A folder with a package.json that names none of these (a monorepo root, a Vue or Solid app) gets "Ulika didn't find a React (Vite or Create React App) or Next.js App Router project here. If this is a monorepo, run the command inside the app's folder." --import-only is refused too. If Ulika cloned the repository only to check it, that clone is removed. --dry-run prints the same answer and exits 26 too. There is nothing to retry, and ulika init --local cannot install on it either. See framework-unsupported.
Error codes#
The code field in a JSON error, and the failure names the CLI prints, with the exit code that goes with each.
usage#
Exit code 2. The command line is wrong or the request names something that cannot be connected, including Ulika's own address (see this-is-ulika). The message says exactly what; see Usage messages.
unauthorized#
Exit code 11. Ulika does not accept this computer's credential. The usual cause is that its approval expired or was revoked. Fix: run the same command again; the CLI forgets the rejected token and starts a new approval. For init, link and the other workspace-token commands, run ulika login, or set ULIKA_TOKEN to a workspace token. A batch also refuses a workspace token ("Batches need an agent token, not a workspace token"): use a connect approval, not login.
auth_required#
Exit code 11. A command that needs authorisation ran where no approval was possible: no stored credential, and no way to ask a person (an agent, a script, --json, or no terminal). The message is "This machine is not authorised for <server>." Fix: run ulika login once in a terminal, or set ULIKA_TOKEN in the environment. With --no-wait on login, the code is "Approval is required before this machine is authorised." (exit code 22).
invalid_token#
Exit code 11. ULIKA_TOKEN is set but is not a workspace token: "ULIKA_TOKEN is set but is not a workspace token" followed by the reason (workspace tokens start with ovl_wt_, and a value that is too short looks truncated). Fix: unset the variable, or set it to a token from Ulika's settings. A value that starts with ovl_at_ is an agent token: it works for connect, not for init.
denied#
Exit code 11. Someone clicked Deny on the approval page. The messages are "The approval was declined in the browser." (for connect) and "The request was denied in the browser." (for login). Fix: run the command again to get a new link when you are ready to approve.
expired#
Exit code 11. The approval link or code ran out before it was used: "The approval link expired before it was used." or "The authorisation request expired before it was approved." Codes last about 15 minutes. Fix: run the command again for a new one.
approval_required#
Exit code 22. See Exit code 22.
token_revoked#
Exit code 12. The hint reads "This machine's authorisation was revoked." Someone revoked it in Ulika's settings, or the account lost access. Fix: run ulika login to authorise this computer again. For a connect approval, a revoked agent shows as unauthorized: run the command again.
forbidden#
Exit code 13. The hint reads "This account may not create projects in that workspace." Your role in that workspace cannot do what the command asked. Fix: ask an owner for access, or have an owner approve. See Roles.
not_found#
Exit code 2. The batch id passed to --resume is not one this agent has. Fix: check the id, or start a new batch without --resume.
bad_request#
Exit code 7. The hint reads "The server rejected the manifest." The scan produced something Ulika refused, or a batch input was refused. Fix: run ulika scan --json and keep the output when you report it.
conflict#
Exit code 7. Ulika refused because the request clashes with existing state, for example when a confirmation was sent but there is no list waiting ("There is no --all list waiting for confirmation"). Fix: read the message; for a missing list, run the all-sites command first and show the list to the person.
protocol_mismatch#
Exit code 8. This CLI speaks a protocol version the server does not. Fix: update the CLI. Use the versioned command your Ulika screens print, or npm i -g https://ulika.co/cli.tgz. npx caches a tarball by address, so an old copy can stay around until you use the new versioned address.
server_error#
Exit code 9. Ulika failed while handling the request ("The server failed while accepting the link", or "while creating the project"). Fix: try again in a moment. A batch that was already submitted keeps running on Ulika; resume it with ulika connect --resume <batchId>.
network#
Exit code 10. The CLI could not reach Ulika ("Could not reach <address>"), usually a dropped connection, a firewall, a wrong --server, or a timeout. During a batch the CLI retries busy or failing answers by itself, starting at one second and up to a minute, for up to eight tries, and prints Ulika is busy, trying again in Ns. During an approval, five failed checks in a row stop it. Fix: check your internet connection, and that ULIKA_SERVER or --server is right. If a batch had already started, nothing is lost: "the batch keeps running. Pick it up with: ulika connect --resume <batchId>".
bad_response#
Exit code 10. Ulika answered, but not with something the CLI understands (not JSON, an unexpected approval state, or an approval without an agent token). Fix: update the CLI to the current version; if it persists, the Ulika server may be an older version that does not support agent connections yet.
site_cap#
Exit code 24. "This agent may take on 50 sites in 24 hours and has N left. Try again later or approve a new agent." Each approved agent can take on at most 50 sites in any rolling 24 hours, across batches. Re-running a list it already has does not count again, and the CLI does not retry. Fix: wait until earlier sites age out of the 24 hours, or approve a new agent with --reapprove.
this-is-ulika#
Exit code 2 when you typed it. "That's Ulika's own address. Pass your website's address instead." (or "That's Ulika's own repository."). Ulika cannot be connected to itself, and both the CLI and the server refuse. If it reaches a site row anyway, the report shows it as an attention reason in plain words: "that is Ulika itself; pass your own website's address instead". Fix: pass your own website's address. Use --server only to point the CLI at a different Ulika.
token_unknown#
Exit code 3. link: "That token does not exist." Fix: generate a fresh pairing token from the project's connect screen.
token_expired#
Exit code 4. link: pairing tokens are short lived on purpose. Fix: generate a new one and run link again.
token_used#
Exit code 5. link: pairing tokens are single use. Fix: generate a new one.
project_missing#
Exit code 6. link: the project the token belongs to no longer exists. Fix: create the project again with ulika init or ulika connect.
Pairing token shape#
link checks the token before scanning: it must start with ovl_live_ ("Tokens start with "ovl_live_"."), must not look truncated ("Token looks truncated."), and may contain only letters, digits, _ and - ("Token contains characters that are not part of a pairing token."). Exit code 2.
Init and local connect failures#
These come from ulika init, and from ulika connect <url> when it runs through your own checkout. In JSON they appear as code.
empty_scan#
Exit code 14. "No editable content was found in this source checkout." The scanner reads static text in JSX files, and it found none. Fix: run ulika scan to see what the extractor read, or point --dir at the folder that holds the site. The extractor reads .tsx, .jsx, .ts, .js and .mjs; Astro, Svelte and Vue files are recorded as skipped with a note.
repository_mismatch#
Exit code 7. Either Vercel says the address is served by a different repository than the one you named with --repo ("Vercel confirms ... but --repo names ..."), or the checkout is not the repository you named ("The selected checkout is ..., but --repo names ..."). Nothing was cloned or imported. Fix: confirm which GitHub repository the Vercel project builds, then run again with the matching --repo, or pick the correct checkout.
bad_site_url#
Exit code 2. "<address> is not a site address Ulika can connect." Fix: pass a public https address such as https://your-site.com.
source_resolution_failed#
Exit code 2. You pointed at a checkout with --dir but Ulika could not resolve the site through Vercel. The hint says to check Vercel access, choose the owning team with --scope, or finish in the browser and prints the link. Fix: make sure vercel is signed in (vercel login), pass --scope <team>, or use ulika connect <url> without local options so Ulika's GitHub App does the lookup.
project_required#
Exit code 2. "There is no website project in this directory, and none is needed: run ulika connect https://your-site.com." You ran init somewhere that is not a website checkout. Fix: run ulika connect https://your-site.com; nothing local is needed.
site_url_required#
Exit code 2. "No site given. Run: ulika connect https://your-site.com ..." init found no site, no checkout and no --dir, and it cannot ask because there is no terminal (or --json is set). Fix: pass the address.
domain_confirmation_required#
Exit code 25. "This repository advertises <address>, while you requested <address>." The command could not ask (no terminal). Fix: run again with --confirm-domain to associate only the address you gave with that repository. See Exit code 25.
domain_not_confirmed#
Exit code 25. "No project was configured because the association was not confirmed." You answered no when asked. Nothing was imported. Fix: run ulika connect <address> again and confirm if you want that address associated with the repository.
framework-unsupported#
Exit code 26. See Exit code 26. In --json the status is unsupported and result.nextAction is none-unsupported-framework. A remote connect reports the same sentence for the site as a failure ("Ulika can't install on Astro sites yet. It supports React and Next.js. No project was created."). A project whose install Ulika refused after it was created shows Not connected: installation failed with the recorded cause and a Delete project button on the dashboard and on its page. Ulika shows this only when it recorded the refusal; a project with no recorded refusal shows its normal connection state. Delete project there works only for a project that is not connected: a connected one is deleted from its Settings.
installation_failed#
Exit code 16. See Exit code 16.
bad_options#
Exit code 2. "Activation cannot be combined with import-only mode." See Usage messages.
Problems with your own tools#
The local path calls git, vercel and gh on your computer. A failure reads "<tool> failed (<last line of its error>). Check access and authentication (vercel login, gh auth login, or git credentials and working tree)." Other messages you can see there:
| Message | Fix |
|---|---|
| "This Vercel domain has no linked project." | The address is not on a Vercel project you can see. Check the team with --scope, or use ulika connect <url> without local options. |
| "The Vercel project needs a linked GitHub repository. Use --dir for other Git providers." | The Vercel project is not connected to GitHub. Connect it in Vercel, or point --dir at a checkout. |
| "Repository mismatch in <folder>. Use --dir with the correct checkout." | Ulika's cached clone under ~/.ulika/repositories points at another repository. Pass the correct --dir. |
| "Local changes in <folder>. Commit them or use --dir before reconnecting." | The cached clone has uncommitted changes. Commit or discard them, or use your own checkout with --dir. |
| "Expected production branch <name> in <folder>." | The cached clone is on another branch. Switch it to the production branch. |
| "Commit untracked source and Vercel configuration before installing." | A file the import needs is untracked. Commit it. |
| "The source checkout must match the latest production branch. Pull it before running init." | Your checkout is behind. Pull first. |
| "Commit tracked local changes before automatic installation, or use --import-only." | You have uncommitted edits. Commit them, or import without installing. |
| "Run init from the Vercel project root directory." | Run it from the folder Vercel builds from. |
| "The checkout does not match the Vercel production repository and branch." | Your checkout is not the repository and branch Vercel deploys. |
| "Ulika can't install on <framework> sites yet. It supports React and Next.js." | See Exit code 26. init now stops with this before creating anything. |
| "Automatic installation needs a deployed Vercel URL and its linked GitHub repository. Use --import-only to import without installing." | Pass the deployed address, or import without installing. |
| "The connector preview failed to build. Check its Vercel logs; production was not changed." | Fix the build error in Vercel, then run again. |
| "Preview proof is not verified yet. Re-run init to resume..." | The preview is not ready or is protected. Re-run to resume; for protected previews set ULIKA_VERCEL_BYPASS or check Vercel account access. |
| "Production changed during preview verification. Pull and re-run init." | The production branch moved. Pull and run again. |
| "GitHub did not merge the connector. Resolve branch protection requirements and re-run init." | Branch protection blocked the merge. Satisfy it, or merge the pull request yourself. |
| "The connector is merged, but production is not verified. Re-run init to resume." | The live site does not show the connector yet. Wait for the deploy and re-run. |
Usage messages#
These are exit code 2. Each one means the command was typed in a way the CLI refuses to guess about.
| Message | Fix |
|---|---|
| "Unknown option --x." | A misspelled or unsupported option. The CLI never ignores one silently. See the CLI reference. |
| "--x needs a value." | A value option has no value, or the next word starts with -. Write --x value or --x=value. |
| "--x does not take a value." | An on/off option was given =value. |
| "Unknown command "x"." | Run ulika --help for the list. |
| "No such directory: <path>" or "<path> is not a directory." | The --dir path is wrong. |
| "--server must be an https origin like https://ulika.co" and "--server must use https" and "--server must be an origin only" | Pass only the origin: no path, query, credentials. Plain http is accepted only for localhost. |
| "Say which sites to connect: --all, --urls <list>, --repos <owner/name,…>, or a site URL." | connect needs something to connect. |
| "--all already includes every site; drop the list or drop --all." | Choose one. |
| ""x" is not a repository. Use owner/name." | A repository must look like acme/website. |
| ""x" is not a site address. Use something like https://your-site.com." | Fix the address. |
| "--repo goes with exactly one site URL: ulika connect https://site.com --repo owner/name." | The repo option pairs one address with one repository. |
| "--repo is for one URL ... Use --repos only with a batch." | Same, from the command-line check. |
| "For one URL, use --repo owner/name. --repos is a batch list and would add independent sites." | Single address plus --repos is refused. |
| "--repo needs one GitHub repository in owner/name form." | One repository only. |
| "--repo associates one deployed site URL with its repository. Use it with init <siteUrl>, not with --dir or a batch." | Drop --dir, or drop --repo. |
| "Provide the site URL once, either positionally or with --url." and "Provide one site URL, either positional or with --url." | Give the address once. |
| "--resume picks up an existing batch; it cannot be combined with a list of sites." | Use --resume alone. |
| "--wait-timeout is a number of minutes between 1 and 120." | Choose a number from 1 to 120. |
| "Single-site connect prepares a reviewable PR. Use --activate only after reviewing it; batch approval flags do not apply." | You mixed local options with batch approval options. Use one path. |
| "--import-only and --activate cannot be combined." | Choose one. |
"--repos is a batch list for connect. For one URL and repository, use init <siteUrl> --repo owner/name." | Same idea for init. |
| "--check needs one site address: ulika connect https://your-site.com --check" | Pass one address. |
| "Nothing to connect." | No sites were given. |
| "ulika link needs a pairing token. To create a project instead, run ulika init." | Pass the token, or use init. |
| "Usage: ulika codex install or ulika codex uninstall" (the real text separates them with a vertical bar) | The action is missing or misspelled. |
Preflight findings#
ulika connect <url> --check lists everything that would stop a site from connecting, all at once, as blockers (must be fixed) and warnings (nothing is blocked). Each comes with a plain message and one fix link. In JSON, each is { code, message, fix: { label, url } }.
| Code | Kind | Meaning and fix |
|---|---|---|
site-address-invalid | Blocker | The address is not one Ulika can use. Enter the full address, like https://example.com. |
github-not-installed | Blocker | Ulika is not connected to GitHub for this workspace, so it cannot see the code behind the site. Use the link to connect GitHub. |
repository-not-accessible | Blocker | Ulika's GitHub App cannot see the repository you named. Give it access to that repository. |
repository-not-specified | Blocker | No repository for the site was found in the GitHub accounts Ulika can see. Pick the repository that builds it. |
ambiguous-repository | Blocker | More than one repository could build the site, or the only match looks like a backup or copy. Pick the right one. |
repository-connected-elsewhere | Blocker | The repository is already connected to a live project in another Ulika workspace, so Ulika will not change it. Disconnect it there first. |
connector-held-elsewhere | Blocker | The repository carries a connector that belongs to a live project in another workspace. Disconnect it there first. |
connector-foreign-files | Blocker | The repository already has files under .ulika/ that Ulika did not write. Review them, then run again. |
vercel-not-connected | Warning (blocker when the site's builds read a build token) | Vercel is not connected to this workspace, so previews are not verified automatically. Use the link to connect Vercel. |
vercel-project-not-found | Blocker when the site's builds read a build token, otherwise reported as host-not-on-vercel | No Vercel project in the connected account serves the site. Connect the Vercel account that owns it. |
vercel-token-invalid | Blocker when the site's builds read a build token | A connected Vercel account was revoked or expired. Reconnect the account the message names. |
vercel-no-permission | Blocker when the site's builds read a build token | A connected account sees the project but has no permission on it. Use an account that does. |
host-not-on-vercel | Warning | The site is not on Vercel and publishes through Git (a Vite or React build). A Next.js site needs Vercel, so it gets a blocker instead. |
vercel-not-git-linked | Blocker | The Vercel project is deployed outside Git, so nothing would build a change. Use Connect this site to GitHub. |
vercel-linked-to-other-repository | Blocker | The Vercel project deploys a different repository or branch than the one chosen. Pick the repository that builds the site. |
vercel-project-held-elsewhere | Blocker | The Vercel project is connected to a live project in another Ulika workspace. Disconnect it there first. |
vercel-project-in-use | Blocker | The Vercel project is used by another project in this workspace. Open that project and disconnect it first. |
address-on-platform-host | Warning | The project also answers on another address. Ulika keeps the address you gave. |
previews-protected | Warning | Vercel Authentication protects previews. Ulika tries a Protection Bypass, or verifies through Vercel's own deployment status. |
legacy-token-variable | Warning | An older ULIKA_BUILD_TOKEN variable was created by another tool and is left alone; Ulika stores ULIKA_CONNECTOR_TOKEN instead. Delete the old one when convenient. |
unseen-deploy-hooks | Warning | Vercel does not show Ulika the project's deploy hooks, so earlier runs may have left duplicates. Nothing is blocked. |
delivery-unknown | Warning | The read of the repository's package.json failed with a GitHub error, so --check did not check whether the site needs Vercel. After a rate limit or outage, run the command again; if the message says the installation no longer allows it, reconnect GitHub first. A package.json that is absent, too large or not a regular file infers nothing and prints nothing. |
large-repository | Warning | The repository is large or carries big media. Ulika reads only the text it needs; moving media out of git makes it faster. |
Attention reasons in the report#
These are the reasons a site is put on the needs your attention list. Each has exactly one next action. The CLI prints them as a plain sentence; with --json you get the code. Ulika never guesses at these and never retries them by itself. Fix the thing, then run the same command again.
ambiguous-repository#
"could not tell which repository serves this site". Ulika ties an address to a repository only when certain. More than one candidate, or only a copy, ends here. Fix: pass --repo owner/name with the right repository.
app-permissions-not-accepted#
"Ulika's updated GitHub permissions are not accepted yet". Fix: open the link and accept the updated permissions on GitHub.
repository-not-in-installation#
"the workspace's GitHub App could not confirm this repository". The GitHub App is not allowed to see that repository. Fix: open the link and give Ulika's GitHub App access to it. Local init uses your own gh login and may have separate access.
installation-access#
"Ulika's GitHub App is suspended or removed". Fix: reinstall or unsuspend the app from the link.
branch-protection#
"branch protection blocks the change". Your branch rules need a review or checks Ulika cannot satisfy. Fix: approve and merge the connector pull request on GitHub; Ulika then checks your live site by itself, and the batch resumes after the merge.
repository-connected-elsewhere#
"already connected in another Ulika workspace". When you belong to that workspace, the next line names it and the project (for example “Main”, project “Nutricion”): delete or disconnect that project, then run again. When you do not, Ulika says only that it is a workspace you are not a member of, and never names it: sign in with the account that owns it, or ask its owner.
unsupported-or-too-large#
"this site cannot be connected from GitHub alone". The repository is too big or has no text Ulika could find. Fix: move large videos and images out of git (Git LFS or your host's storage), or connect from the website's checkout with ulika init --local.
vercel-not-git-linked#
"its Vercel project is not connected to GitHub; open the link and press Connect this site to GitHub". Fix: use that link and button; then run again.
vercel-project-conflict#
"its Vercel project needs attention first". The problem list under it names the one fix: Vercel not connected, project not found, deploying another repository, held by a project in another workspace, or already used in this workspace. See the matching codes in Preflight findings.
vercel-not-connected#
"Vercel is not connected to this workspace". Fix: open the link and connect your Vercel account. Within 24 hours of the stop, connecting it resumes the site by itself; after that, run the command again.
vercel-wrong-account#
"the connected Vercel account cannot see this site's project". The line under it names every account searched. Fix: open the link and add the account that owns the project. Within 24 hours of the stop, adding the account resumes the site by itself; after that, run the command again.
vercel-token-invalid#
"the Vercel credential no longer works". Fix: open the link and reconnect the account named under it. Within 24 hours of the stop, reconnecting the account resumes the site by itself; after that, run the command again.
vercel-unavailable#
"Vercel did not answer; run the command again to retry". Fix: Ulika retries a few times during the run; if it still fails, run the command again.
connector-foreign-files#
"the repository already has files under .ulika/ that Ulika did not write". Fix: review those files, then run again.
collections-or-pending-drafts#
"has pending changes in Ulika". Fix: publish or discard the pending changes in the project, then run again.
connector-already-installed#
"the repository already has this connector but Ulika has no record of installing it". Fix: either disconnect the site in Ulika and connect it again, or remove the .ulika folder from the repository and run again. If Ulika does have a record, running the command again verifies it.
content-conflict#
"an existing Ulika project already holds this content differently". An existing project binds the same fields as another kind. Fix: open that project to migrate or delete the conflicting fields, then run again.
source-changed#
"the source changed while connecting", with a line naming the field Ulika could not locate. Fix: read the repository again in Ulika, review the connector, then run the command again.
build-failed#
"the preview build failed". Your host reported the build of the connector branch as failed, read from Vercel's API or from the status, check or deployment your host left on the pull request. The action links to the build log. Fix: open the build log, fix the error, run again.
build-slow#
"the build is taking longer than 30 minutes". Fix: check the build on your host, then run again. After a merge, a host that is not still building is reported as production-unverifiable instead.
build-unobservable#
"Ulika cannot see this site's builds". Neither a connected Vercel account nor GitHub's statuses and checks could be read for the connector commit, and the detail says why: a permission to accept, nothing to approve, Ulika unable to check its GitHub access right now, or a host that reported nothing to GitHub. A build that failed is build-failed, not this. Fix: check the pull request's checks; if they did not fail, open the Activate link and click Activate; the CLI waits for it.
preview-protected#
"Vercel's login wall blocks Ulika from reading the preview". Ulika waited three minutes. Fix: open the deployment in Vercel; if the build failed fix it, if it is ready run again. Or turn off Vercel Authentication for previews under Settings > Deployment Protection.
preview-unreadable#
"the preview built but Ulika cannot read it". Waited ten minutes. Fix: open the preview, check that it loads, run again.
pull-request-awaiting-merge#
"the pull request is waiting for you to merge it". The common case with review-first. Fix: open the Ulika link and click Activate. The CLI keeps waiting for you, and ends when the site is live.
pull-request-closed#
"the pull request was closed". A person closed it on GitHub, so Ulika does not open another by itself. Fix: run the same command again with --reopen to open a new connector pull request.
connector-language-changed#
"the open connector pull request was prepared for the other language and someone changed it, so Ulika will not touch it; close it on GitHub, then run again". Ulika replaces its own untouched pull request by itself, so this appears only when someone added commits to it or it is not Ulika's. Fix: close the pull request the link opens, then run the command again for a new one in the right language. See connector-language-changed.
head-moved#
"someone pushed to the connector branch". Fix: review the commits pushed onto the connector branch, then run again.
production-proof-missing#
"the live site does not show the connector yet". The connector is merged and the live site does not serve its proof. Fix: check on your host that the merge was deployed, then run again.
production-build-failed#
"the production build failed after the connector was merged". Ulika reverted the connector (or opened the pull request that does). Fix: review the revert pull request the link opens, fix what broke the production build, then run again. See Connect attention reasons.
production-revert-failed#
"the production build failed after the connector was merged and no revert exists; revert the connector on GitHub". Ulika could not revert the connector, or the merge was not Ulika's, so your production builds keep failing until it is removed. Fix: revert the install pull request the link opens, then run again. See Connect attention reasons.
production-unverifiable#
"the connector is merged but Ulika cannot confirm your live site serves it; press Activate anyway in the dashboard". The connector is merged, your host did not report a failed build, and 30 minutes passed without the live site showing the connector (typically a private, password-protected or unreachable site). Fix: if your site works, open the link and press Activate anyway in the dashboard; the CLI sees the site go live when you do. If it does not work, fix the production build first. See Connect attention reasons.
reapproval-required#
"this organisation needs a fresh approval (weekly)". Fix: run the same command with --reapprove and approve again. It picks up where it stopped. See weekly re-approval.
expansion-failed#
"Ulika could not list your repositories". Applies to the whole batch, not one site; it appears when --all could not list repositories after three tries. Fix: run the command again; check that Ulika's GitHub App is still installed.
project-deleted#
The project this site was connected to no longer exists. The site is detached and its history kept. The CLI prints the code as it is. Fix: run the command again to connect it fresh.
Failure reasons#
These are the reasons a site ends as failed. Run the command again to retry.
credential-revoked#
"this machine's approval was revoked". The agent token stopped working during the batch. Fix: run the command again and approve.
internal-error#
"Ulika hit an unexpected error". Retried by Ulika first. Fix: run again; if it repeats, keep the --json output.
github- failures#
Failures from GitHub are named github- plus a reason: github-installation-suspended and github-installation-revoked (Ulika's access to GitHub was suspended or removed; restore or reconnect it), github-repository-gone (the repository was renamed, transferred or removed from the installation), github-permission-downgraded (Ulika's GitHub permissions were reduced; accept them again), github-rate-limited (GitHub asked Ulika to slow down; Ulika waits and continues by itself first) and github-unavailable (GitHub did not answer). The other two, github-not-configured and github-sign-in-not-configured, only occur on a Ulika deployment that is not set up for GitHub.
Other failure names#
A site can also fail with a short name such as connection-expired, reconcile-busy, repository-id-unknown, or discovery-<status> and import-<status> (where Ulika's own reading step ended in an unexpected state). These are transient or internal. Fix: run the command again; if the same name returns, keep the --json output.
Still stuck?#
Run the command again with --json and keep the output (the report or error line). Check Connect attention reasons, GitHub problems and Vercel problems, and the FAQ.
Was this page helpful?