UlikaDocs
Open Ulika

Getting started

  • Ulika documentation
  • How Ulika works
  • Requirements
  • Quickstart

Connect a site

  • Connect from the dashboard
  • Connect with the CLI
  • Connect with an AI agent
  • Approving a connection
  • Private previews
  • The GitHub App
  • Connect Vercel

Integrations

  • GitHub integration
  • Vercel integration
  • Netlify
  • Claude Code
  • Codex
  • MCP tools

Editing

  • The editor
  • The style panel
  • Sections and pages
  • Mobile preview, autosave and drafts

Publishing

  • Publish your changes
  • History and restoring a version
  • When a publish fails

Team

  • Team roles
  • Inviting people

Projects

  • Project settings
  • Delete a project
  • Website code

Troubleshooting

  • Needs attention reasons
  • Vercel problems
  • GitHub problems
  • CLI errors and exit codes
  • Frequently asked questions

Security and privacy

  • Security and privacy overview

CLI

  • CLI reference
  • CLI changelog

Troubleshooting

Needs attention reasons

Every reason a site connection stops and asks for you, what it means, how to fix it step by step, and whether Ulika retries by itself.

Last updated October 25, 2026

When you connect a site with ulika connect (or an AI agent does it for you), Ulika works through the steps on its own: find the repository, read the site, import the content, prepare the connector, open a pull request, wait for a preview, merge, and confirm your live site. When it reaches something only a person can decide or fix, the site stops with a reason and one next action. That is a needs attention state, and this page lists every reason.

Where you see these#

  • In the terminal. The report ends with a line like 2 live · 1 needs your attention · 0 failed, then each site with a short sentence and a link or command. The exit code is 20 when no site is live and none failed (every site needs a person). With --json you get the reason as a code such as branch-protection.

  • In the dashboard. On the connect screen, while Ulika waits for your project, a Runs that stopped list shows the site and the message, with a Fix it link. It covers runs from the last 24 hours.

  • In an AI agent's report. The agent shows each attention item with its reason and its single next action.

The reasons in this page are the codes you see in --json output and in the reason field of the connect events. Each one has its own heading below. Use your browser's find to jump to it.

How retries work#

  • A needs attention state does not fix itself. The site waits for you. Do the one action shown, then run the same command again; it picks up where it stopped and does not connect anything twice.

  • Exception: waiting for a merge. If a site is waiting for the connector pull request to be merged (pull-request-awaiting-merge, build-unobservable, branch-protection), Ulika continues by itself as soon as GitHub reports the merge. You do not need to run the command again.

  • Temporary problems are retried automatically. A network hiccup, GitHub or Vercel being slow, or a step that is already running elsewhere is retried up to five times, waiting longer each time (15 seconds, 30 seconds, and so on). Only after that does the site show as failed (see Failed runs).

  • Rate limits are pauses, not errors. If GitHub asks Ulika to slow down, the site shows paused, continuing at 14:05 and resumes by itself. Ulika writes to GitHub at a measured pace (about one write per second per installation), and works on at most three sites per workspace at a time, so a large batch takes a while.

  • A safety net runs hourly. Connectors waiting on a merge or a build are re-checked on a schedule even if a notification from GitHub is missed.

Related pages: Vercel problems, GitHub problems, CLI problems and Failed builds.

Choosing the repository#

ambiguous-repository#

What you see. In the terminal: "could not tell which repository serves this site". The message gives the exact command, for example ulika connect https://your-site.com --repo owner/name, followed by other likely candidates.

When the only hint is a repository whose name matches the site address (for example nutricion-disi.vercel.app and a repository called nutricion-disi), the message reads "Ulika found a repository named like this site: owner/name. If it is the right one, run: ulika connect <url> --repo owner/name". A name match is only a guess, because vercel.app and netlify.app names are global and anyone can take them, so Ulika never acts on it unattended. Run the command if it is the right repository. Generic names such as app, web, docs or demo never produce a suggestion.

Why it happens. Ulika only connects a site to a repository when it is certain. It is certain when exactly one repository has a successful production deployment, reported by your hosting provider, on the site's address, or when a repository's own ulika.config.json names the site. A homepage field or a similar name is not enough, because anyone with write access can type those. Typical causes are a custom domain GitHub cannot map to a repository, two repositories that claim the same address, or a match that looks like a backup or copy (a name with backup, copy, old, archive, mirror, a fork, or a random suffix).

How to fix it.

  1. Decide which repository really builds the site.

  2. Run the command Ulika printed, with --repo owner/name set to that repository.

  3. Wait for the run to continue.

If you approve in a browser, the approval page can ask this for you: it lists the likely repositories and the CLI uses the one you click (nothing is preselected for a name match: None of these is chosen until you click the repository), so the command above is only needed when you connect through an MCP client or skip the page. When the page lists several repositories, choose None of these to skip the pick; the command above then applies. Candidates are listed per GitHub installation you approved with, so an organisation member may see repository names they cannot open on GitHub. Only the first site of a multi-site run that is not already paired with --repo gets a pick; the others use the command above.

Retries by itself? No. Ulika never guesses. Once the pair works, a connected project for that address is used next time.

repository-not-in-installation#

What you see. "the workspace's GitHub App could not confirm this repository" or, in the dashboard, messages such as "Ulika's GitHub App cannot see owner/name. Add it under Repository access for owner on GitHub, then run the command again", "Install Ulika's GitHub App, then run this command again", or "Give Ulika's GitHub App access to this repository".

Why it happens. Ulika can only see repositories you selected when you installed its GitHub App. GitHub deliberately answers the same way for a repository that does not exist, one that was renamed or transferred, and one the App was not given. Ulika cannot tell these apart.

How to fix it.

  1. Open the link in the message. It goes to the App's page for the right GitHub account.

  2. Under Repository access, add the repository (or choose All repositories).

  3. Save, then run the command again.

If the repository is in another organisation or account than the ones you approved, the message says to install Ulika's GitHub App there and then run ulika connect <your site> --reapprove: an approval only covers the accounts that had the App when you approved. Install first, re-approve second.

If the repository lives in an organisation, an organisation admin may need to approve the change. See GitHub problems.

Retries by itself? No.

installation-access#

What you see. "Ulika's GitHub App is suspended or removed". The action is Unsuspend Ulika's GitHub App for this account or Reinstall or unsuspend Ulika's GitHub App.

Why it happens. Someone suspended or uninstalled the App on that GitHub account, or its access was revoked. When an installation is removed, agent logins tied to it are revoked too.

How to fix it.

  1. Open https://github.com/settings/installations (for an organisation, the organisation's installed apps page).

  2. Find Ulika and Unsuspend it, or install it again and select the repositories.

  3. Run the command again. If an agent login was revoked, approve it again when asked.

Retries by itself? No.

app-permissions-not-accepted#

What you see. "Ulika's updated GitHub permissions are not accepted yet". The action is Accept Ulika's updated GitHub permissions.

Why it happens. Writing the connector needs Contents: read and write and Pull requests: read and write. If the App was installed with read-only access, or the permissions were later reduced, Ulika stops before writing anything. GitHub asks an account admin to accept permission changes. Nothing is written until they do.

How to fix it.

  1. Open the link in the message (the App's installation page on GitHub).

  2. Accept the pending permission request. An organisation owner may need to do this.

  3. Run the command again.

Retries by itself? No.

reapproval-required#

What you see. "this organisation needs a fresh approval (weekly)". The report adds "Run the same command with --reapprove to approve this machine again; it picks up where it stopped."

Why it happens. For repositories owned by a GitHub organisation, an agent's approval is valid for 7 days. Ulika cannot see when someone leaves an organisation, so the weekly re-approval limits how long a former member's machine could keep writing. Personal accounts and read-only steps are not affected.

How to fix it.

  1. Run ulika connect <your usual arguments> --reapprove.

  2. Approve the machine in the browser when the page opens.

Retries by itself? No. After you approve, the site continues from where it stopped.

this-is-ulika#

What you see. "that is Ulika itself; pass your own website's address instead". The action is Pass your website's address instead.

Why it happens. The address or repository you gave belongs to Ulika's own product. Ulika refuses to connect to itself. Nothing was written, and the input is never queued.

How to fix it. Run the command again with your own website's address, for example ulika connect https://your-site.com.

Retries by itself? No.

repository-connected-elsewhere#

What you see. "already connected in another Ulika workspace", followed by one of two sentences.

  • If you are a member of the workspace that holds the repository: "<repository> is connected in your workspace “<workspace>”, project “<project>”. Delete that project or disconnect it there, then run again." with a link to that project.

  • If you are not: "This repository is connected to another Ulika workspace you are not a member of. If it is yours, sign in with that account and remove it there; otherwise ask that workspace's owner." Ulika never names a workspace, a project or an owner you cannot already see.

A related message says the repository already carries a connector from a live project in another workspace, or files Ulika did not write.

Why it happens. A repository can be bound to one workspace at a time. Two workspaces publishing into one repository would overwrite each other's content, so Ulika refuses the second.

How to fix it.

  1. Find the workspace that has the repository connected. If you are a member, the message names it. If it does not, the workspace belongs to someone else (or to an account you are not signed in with): sign in with that account, or ask its owner.

  2. In that workspace, open the project's Settings and choose Disconnect in the Danger zone, or delete the project.

  3. Run the command again in your workspace.

Retries by itself? No.

connector-foreign-files#

What you see. "the repository already has files under .ulika/ that Ulika did not write". The fix is Review those files, then run again.

Why it happens. Ulika owns only the files it creates inside .ulika/. If that folder already contains other files, or .ulika/connector.json cannot be read, Ulika will not overwrite them.

How to fix it.

  1. Open the repository and look at the files under .ulika/.

  2. If they are leftovers you no longer need, remove them in a commit on your default branch. If you need them, move them elsewhere.

  3. Run the command again.

Retries by itself? No.

Reading the repository and installing the connector#

unsupported-or-too-large#

What you see. "this site cannot be connected from GitHub alone". The sentence varies:

  • "This repository is bigger than Ulika can read (it reached ...)". Move large videos and images out of git, using Git LFS or your host's storage, or connect from the website's checkout with ulika init --local.

  • "Reading this repository took too long. Run the command again; if it keeps happening, connect from the checkout with ulika init --local".

  • "Ulika could not find editable text in this repository. Connect it from the website's checkout with ulika init --local".

  • "Ulika cannot install its connector on this repository automatically (...)". The part in brackets is one of: unsupported layout, wrong root directory, unreadable config, build command missing. An unsupported framework is not this reason: it ends the site as framework-unsupported.

Why it happens. Ulika reads a snapshot within fixed limits (download size, number of files, time) and installs connectors for Next.js App Router sites and for sites built with Vite or Create React App. Other layouts, very large repositories, and sites it cannot find a build command for need the CLI.

How to fix it.

  1. If the message names a size limit, shrink the repository (move media out of git).

  2. Otherwise, check out the website's repository on your computer and run ulika init --local inside it.

  3. See Connect with the CLI for how the local scan works.

Retries by itself? No, except that a "took too long" run is worth one more attempt.

collections-or-pending-drafts#

What you see. "has pending changes in Ulika". The action is Publish or discard the pending changes in Ulika, then run again.

Why it happens. A connector commit lives in your repository, which can be public, so it cannot carry unpublished drafts. Collections (repeating items such as blog posts) also need a different connector than the build-time one.

How to fix it.

  1. Open the project in Ulika.

  2. Publish or discard the pending changes. If the project has collections, use the CLI or the Next.js connector for it.

  3. Run the command again.

Retries by itself? No.

content-conflict#

What you see. "an existing Ulika project already holds this content differently". The action is Open the existing project in Ulika to migrate or delete the conflicting fields, then run again.

Why it happens. A project for this site already exists, and importing again would overwrite some fields it uses as a different kind of content (for example a field bound as text that the new scan reads as an image). Retrying cannot fix a decision like that, so a person has to choose.

How to fix it.

  1. Open the existing project from the link.

  2. Delete or migrate the conflicting fields.

  3. Run the command again.

Retries by itself? No.

connector-already-installed#

What you see. "the repository already has this connector but Ulika has no record of installing it". The action says to disconnect the site in Ulika and connect it again, or remove the .ulika folder from the repository and run the command again. A softer version says "This repository already carries this connector. Run the command again to verify it".

Why it happens. The connector files are already in the repository, but this workspace has no connection that matches them (for example the project was deleted, or it was installed from another machine). Ulika will not take over a connector it cannot account for.

How to fix it. Either:

  1. Disconnect or delete the old project in Ulika, then run ulika connect again; or

  2. Remove the .ulika folder (and the build entry the connector added) from your repository in a commit, then run the command again.

Retries by itself? No.

project-deleted#

What you see. "This project no longer exists. Run the connect command again to set it up afresh".

Why it happens. The Ulika project this site was connected to was deleted. Ulika detaches the old record (its history is kept) so it never reports a deleted project as live.

How to fix it. Run the connect command again. A new project is created.

Retries by itself? No.

Your hosting#

vercel-not-git-linked#

What you see. "its Vercel project is not connected to GitHub; open the link and press Connect this site to GitHub".

Why it happens. The site is deployed on Vercel without a Git connection (for example uploaded with the Vercel CLI), so nothing would ever build a change from the repository.

How to fix it.

  1. Open the link in the message. It opens the project's Connect this site to GitHub card.

  2. Click Connect this site to GitHub. This links the Vercel project to the repository; your site keeps running as it is.

  3. Run the connect command again.

Details: Vercel problems.

Retries by itself? No.

vercel-not-connected#

What you see. "Vercel is not connected to this workspace". A Next.js site needs Vercel and the workspace has no connected account. Nothing was written.

Fix. Open the link and connect Vercel. The site continues by itself within 24 hours; later, run ulika connect again.

vercel-wrong-account#

What you see. "the connected Vercel account cannot see this site's project". The line under it names the host and every account searched, or says that one account has no permission on the project.

Fix. Open the link, add the account or team that owns the project, or ask its owner for access. The site continues by itself within 24 hours.

vercel-token-invalid#

What you see. "the Vercel credential no longer works". A connected account was revoked or expired, and it is named under the sentence.

Fix. Reconnect that account from the link.

vercel-unavailable#

What you see. "Vercel did not answer; run the command again to retry".

Fix. Ulika retries a few times during the run; if it still fails, run ulika connect again.

vercel-project-conflict#

What you see. "its Vercel project needs attention first". The report lists every problem found, each with its own sentence and one fix.

Why it happens. Something about the Vercel project blocks the connection: Vercel is not connected, no project serves the address, the project deploys a different repository or branch, another Ulika project already uses it, the address is only a platform address, or a connector step was refused.

How to fix it. Work through the listed problems. Each one is explained in Vercel problems, including vercel-project-not-found, vercel-linked-to-other-repository, vercel-project-held-elsewhere, vercel-project-in-use and host-not-on-vercel.

Retries by itself? No.

Builds and previews#

build-failed#

What you see. "the preview build failed". The action is Open the host's build log, or Open the pull request's checks when your host gave no log link.

Why it happens. Your host reported that the build of the connector branch failed or was cancelled. Nothing was merged and your live site is unchanged. Ulika learns this from the Vercel API when a connected Vercel account can see the project, and otherwise from the status, check or deployment your host leaves on the pull request in GitHub. When the Vercel API answers for the project, GitHub is not consulted to overrule it. From GitHub only the newest attempt counts (a successful redeploy of the same commit replaces an earlier failure), and in a monorepo only your own Vercel project counts: another project's failure on the same commit is ignored. If several Vercel projects report and Ulika cannot tell which one is your site, it treats the build as unreadable (build-unobservable) rather than failed. Clicking Activate on a failed build never merges it: you see "The preview build failed on your host" with the same build log link.

How to fix it.

  1. Open the build log from the link (your host's page for the failed build, or the pull request's checks when the host gave no link) and read the error.

  2. Fix the cause on your side (often an existing build problem that the connector branch exposed).

  3. Run the command again.

Related: Failed builds.

Retries by itself? No. Failure is only reported when your host says so, never because time passed.

build-slow#

What you see. "the build is taking longer than 30 minutes". The action is Check the build on your host or Check the production build on your host.

Why it happens. Ulika waits up to 30 minutes for the preview build, and up to 30 minutes after merging for your live site to serve the connector. Past that it stops and asks you to look. After the merge, if your host does not say the build is still running (the site is private or unreachable, or the host reported nothing), the reason is production-unverifiable instead.

How to fix it.

  1. Open your host's dashboard and check the deployment.

  2. If it finished, run the command again. If it is stuck, cancel it and trigger a new deployment.

Retries by itself? No.

build-unobservable#

What you see. "Ulika cannot see this site's builds", with the activation link: Open this link and click Activate to put Ulika on your live site. and a sentence saying why Ulika could not read the build. There are four, and the message tells you which one applies: a permission you can accept, a GitHub app that does not request the reads (nothing to approve), Ulika being unable to check its own GitHub access right now, or a host that simply reported nothing to GitHub.

Why it happens. Neither source answered. Ulika could not read the build through Vercel (no connected account can see the project) and could not read it through GitHub (your installation has not accepted the permissions to read commit statuses, checks and deployments, or your host posts nothing there). When Ulika's access is granted, the message says only that your host did not report this build to GitHub; it never claims access is missing. This is only said when nothing could be read: a build your host reported as failed is build-failed, never this. Ulika will not merge on guesswork.

How to fix it.

  1. Open the pull request and look at its checks. If your host's check failed, fix it and run the command again.

  2. If it passed or shows none, open the link and click Activate on the live site. Ulika merges the connector, checks your live site right after, and undoes the change automatically if the live build fails.

  3. Optionally accept the updated GitHub permissions (the Approve Ulika's updated GitHub permissions banner) so previews can be confirmed next time.

When the cause is a permission. If Ulika's installation has not accepted a read it needs, the message names exactly which ones ("Commit statuses", "Checks", "Deployments") and says your host is not the problem. Open the installation settings link in the message (or Settings > Applications > Installed GitHub Apps > Ulika > Configure), choose Review request and accept the new permissions, then run the command again. Ulika reads Vercel's result from GitHub as soon as they are accepted: the commit status and the deployment Vercel posts, each recognised by its author, the vercel[bot] account.

Retries by itself? After the merge happens, yes. Ulika continues by itself and verifies your live site.

preview-protected#

What you see. "Vercel's login wall blocks Ulika from reading the preview". The message explains that Vercel has not reported the deployment ready either.

Why it happens. Vercel Authentication (or a password) protects your previews. Ulika tries to create a bypass for itself; if Vercel refuses, it verifies through Vercel's own deployment status instead. It waits about three minutes before stopping.

How to fix it.

  1. Open the deployment in Vercel. If the build failed, fix it. If it is ready, run the command again.

  2. Or, to let Ulika read previews directly, turn off Vercel Authentication for previews in the project's Settings > Deployment Protection.

More detail: Vercel problems.

Retries by itself? During the first three minutes, yes. After that, no.

preview-unreadable#

What you see. "the preview built but Ulika cannot read it".

Why it happens. The deployment exists but Ulika could not read the connector's proof back from it for ten minutes, for a reason that is not a login wall (it may still be building, or a different revision is being served).

How to fix it. Open the preview and check that it loads, then run the command again.

Retries by itself? For ten minutes, yes. After that, no.

Pull request and your live site#

pull-request-awaiting-merge#

What you see. "the pull request is waiting for you to merge it", with Open this link and click Activate to put Ulika on your live site. and, as a second option, "Prefer GitHub? Review and merge PR #16".

Why it happens. Review first is the default, so Ulika waits for you unless you chose automatic merge (--auto-merge, or the approval-page box). It also waits when Ulika could not merge on its own (see branch-protection). Merging is a deliberate step.

How to fix it.

  1. Open the Ulika link and click Activate on the live site, or review and merge the pull request on GitHub.

  2. Nothing else is needed.

Retries by itself? After the merge, yes. Ulika detects the merge, checks your production site, and marks the site live.

branch-protection#

What you see. "branch protection blocks the change". The message says your branch protection requires a review or checks that Ulika cannot satisfy and asks you to approve and merge the pull request.

Why it happens. Your branch rules need an approving review or required checks. Ulika never asks to bypass your rules.

How to fix it.

  1. Open the pull request from the link.

  2. Approve it (if a review is required) and merge it. A teammate can do this.

  3. Ulika then checks your live site by itself.

Details: GitHub problems.

Retries by itself? After the merge, yes.

pull-request-closed#

What you see. "the pull request was closed". The action is The connector pull request was closed on GitHub. Run the same command again with --reopen, or open the connect screen and press Turn on live editing, to open a new one.

Why it happens. The connector pull request was closed without being merged, so the connector is not installed. Ulika does not open another by itself after a person closed one, because closing it was a decision. A pull request Ulika closed itself (an outdated one it replaced) is not this case: Ulika opens the new one in the same run.

How to fix it. Run the connect command again with --reopen, or open the link and press Turn on live editing. Ulika opens a new pull request.

Retries by itself? No.

connector-language-changed#

What you see. "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". The action reads Pull request #17 was prepared for TypeScript, but this site uses JavaScript. Ulika will not change it because someone other than Ulika changed it or opened it. Close pull request #17 on GitHub, then run the command again. (or the other way round), and links to that pull request.

Why it happens. Ulika writes .js files into a site that does not use TypeScript and .ts files into one that does, because Next refuses to build a .ts file without typescript installed. A pull request in the other language would break your build if merged.

You normally never see this. When the outdated pull request is Ulika's own and untouched, Ulika replaces it by itself: it comments "Ulika replaced this pull request with a new one ... Nothing was merged.", closes it without merging, deletes its ulika/setup branch when the branch is not protected, and opens a new pull request in the right language in the same run. "Untouched" means all of these hold: the pull request is open and unmerged, the GitHub App's own bot account opened it, its branch is a ulika/setup* branch in the same repository (not a fork), the branch still points at the commit Ulika wrote, and every commit on it was written by the App's bot. This message appears only when one of those is not true, for example someone pushed a commit to the branch or the pull request is not Ulika's. Ulika never touches a pull request that someone changed. If the comment cannot be posted, Ulika still closes the pull request and continues. Closing needs Pull requests: Read and write, the permission Ulika already requires.

How to fix it.

  1. Open the pull request from the link and close it without merging.

  2. Run the command again. Ulika opens a new pull request in the right language.

Retries by itself? No.

head-moved#

What you see. "someone pushed to the connector branch". The action is Review the commits pushed onto the connector branch.

Why it happens. Ulika only merges the exact commit it created and checked. If somebody pushed another commit to the ulika/setup branch, it stops.

How to fix it.

  1. Open the pull request and look at the extra commits.

  2. If they are intended, merge the pull request on GitHub yourself. Otherwise close it and run the command again for a fresh one.

Retries by itself? No.

source-changed#

What you see. "the source changed while connecting". The action is Read the repository again in Ulika, review the connector, then run the command again. A line under it names the field Ulika could not locate.

Why it happens. Files that the connector binds to changed on your default branch after Ulika read them. Merging would break your next build, so Ulika stops.

How to fix it. Run the command again. Ulika re-scans and prepares a new pull request.

Retries by itself? No.

production-proof-missing#

What you see. "the live site does not show the connector yet".

Why it happens. The connector is merged, and the live site does not serve its proof. A production build your host reports as failed is production-build-failed or production-revert-failed, never this.

How to fix it. Open your host's production build log and check that the merge was deployed, then run the command again.

Retries by itself? No.

production-build-failed#

What you see. "the production build failed after the connector was merged". The action says what happened to the revert and links the revert pull request, never the install pull request.

Why it happens. After Ulika merged the connector, your host reported that the production build failed. Ulika opened a pull request on ulika/revert that restores every connector file. It is either merged already, waiting for your checks (GitHub merges it when they pass), or opened but not merged because Ulika could not merge it (a required review or check, or GitHub refused). In that case the action says so and links the revert pull request: merge it on GitHub. Your live site kept serving the previous deployment.

How to fix it.

  1. Open the revert pull request from the link. If it is not merged yet, merge it.

  2. Open your host's production build log and fix the cause. A common one is a variable that exists only for Production: the preview build cannot prove the production build.

  3. Run the command again to create a new connector pull request.

Retries by itself? No.

production-revert-failed#

What you see. "the production build failed after the connector was merged and no revert exists; revert the connector on GitHub". The action reads "Ulika could not revert the connector; your production builds will keep failing until it is removed. To undo it: revert the connector install pull request ... on GitHub" and links the install pull request.

Why it happens. The production build failed after the merge, and there is no revert: Ulika tried and could not (GitHub refused it, or a connector file was edited after the merge, which Ulika never overwrites), or the merge was made by a person, and Ulika never reverts those. The connector is still in your repository.

How to fix it.

  1. Open the install pull request from the link, press Revert on the merged pull request, and merge the revert.

  2. Open your host's production build log and fix the cause.

  3. Run the command again to create a new connector pull request.

Retries by itself? Ulika tries the revert again the next time it looks at the site, unless a person made the merge.

production-unverifiable#

What you see. "the connector is merged but Ulika cannot confirm your live site serves it; press Activate anyway in the dashboard". The action is the link to your project in Ulika, where the Activate anyway button is.

Why it happens. The connector pull request is merged (by you on GitHub, or by Ulika on a preview it could not read), and Ulika waited 30 minutes for your live site to serve the connector's proof without seeing it. Your host did not report a failed build. Ulika says which of three cases it is: your host reports the deploy as live but your site does not show the connector (check the production URL and branch), Ulika cannot read your live site (it looks private, password-protected or unreachable, because Ulika can only read the proof from the public address of the site), or there is no merge commit Ulika could ask your host about. A production build your host reports as failed is production-build-failed, never this, and a deployment your host still reports as building keeps waiting (and ends as build-slow).

How to fix it.

  1. If your site works, open the link and press Activate anyway. Ulika records that you agreed, turns live editing on without the proof, and does not check again. Pressing it asks you to confirm, and records who confirmed. Pressing it is your decision that the site is fine: if the connector is not live, edits you publish are saved to your repository but may not appear on your site, and Ulika will not check again or undo it automatically. Just before it acts, Ulika asks your host once more; if the production build has failed meanwhile, it stops with production-build-failed instead.

  2. If your site does not work, fix the production build on your host first. Ulika keeps checking until you press the button, and activates by itself as soon as the live site serves the connector.

Ulika does not undo a merge you made, so nothing is reverted either way.

Retries by itself? Until the button is pressed, yes: each time Ulika looks and the live site serves the connector, the site goes live and this reason clears.

A note on the 10-minute window. When Ulika merges a connector it remembers the attempt for 10 minutes, so a merge that landed while its answer was lost is still recognised as Ulika's own (and undone automatically if the live build fails). The trade-off: a pull request merged on GitHub within those 10 minutes, on exactly the commit Ulika merged on, is treated as Ulika's; one merged later is always treated as yours and is never reverted automatically.

Whole-batch reasons#

expansion-failed#

What you see. "Ulika could not list your repositories". The action is Run the same command again, or name the sites with --repos owner/name.

Why it happens. With ulika connect --all, Ulika lists your repositories a chunk at a time. After three failed attempts in a row it gives up on the list.

How to fix it. Run the command again, or name the sites yourself with --repos owner/name,owner/other.

Retries by itself? It retries three times with growing waits before showing this.

Failed runs#

A failed site (as opposed to needs attention) is a run that could not continue even after retries. The terminal says failed: with a reason. Run the command again; it picks up where it stopped. These are the reasons:

credential-revoked#

What you see. "this machine's approval was revoked".

Why it happens. The agent login this run used was revoked or expired (30 days, 14 days unused, you revoked it, its approver left, or the GitHub installation was removed).

How to fix it. Run the command again and approve the machine when the browser opens.

Retries by itself? No.

internal-error#

What you see. "Ulika hit an unexpected error".

Why it happens. A step failed unexpectedly after retries.

How to fix it. Run the command again. If it keeps happening, note the site address and the time when you ask for help.

Retries by itself? Already retried up to five times.

framework-unsupported#

What you see. "Ulika can't install on static HTML sites yet. It supports React and Next.js. No project was created." (or Astro, SvelteKit, Nuxt, Remix, Gatsby, RedwoodJS, Expo or React Native), "Ulika supports the Next.js App Router; this site uses the Pages Router.", or "Ulika didn't find a React (Vite or Create React App) or Next.js App Router project at the root of this repository.". A repository whose package.json is missing or not valid JSON fails with its own sentence, not this one.

Why it happens. Ulika reads the repository first and checks, before it imports anything, that it has an installer for the framework. Only React (Vite with its React plugin, or Create React App) and Next.js (App Router) have one today. The check is the same one ulika init runs, so ulika init --local cannot install either.

How to fix it. There is nothing to fix on your side and no command to try. No project was created. A site that is a React or Next.js app inside a folder of a larger repository is not refused by this check: the connector plan reads its own manifest.

Retries by itself? No: the framework does not change on a retry.

repository-id-unknown#

What you see. "repository-id-unknown", or in the browser "GitHub did not return this repository's id, so Ulika cannot make sure no other workspace publishes into it. Nothing was written."

Why it happens. GitHub did not return the repository's numeric id.

How to fix it. Wait a moment and run the command again.

Retries by itself? No.

Reasons that begin with connector-, connect-, preflight-, github-, discovery- or import-#

These carry detail after a colon, for example connector-vercel-failed: ... with the failing step, HTTP status and Vercel's own message. They mean a step failed and retrying did not help. Read the detail, fix the named cause (often one of the Vercel or GitHub items in the linked pages), and run the command again. A reason of the form github-<reason> is one of the GitHub states in GitHub problems.

Connector failure reasons in the browser#

In the browser connect flow, installing the connector can stop with a card that has a title and one next action. In ulika connect the same causes appear as the attention reasons above. Four share their names with attention reasons already covered: head-moved, source-changed, connector-language-changed and repository-connected-elsewhere. The rest are below.

permission-missing#

What you see. "Ulika cannot write to this repository yet". Ulika was installed with read-only access.

Fix. On GitHub, open the App's Permissions & events, set Contents and Pull requests to Read and write, then accept the change on the installation. Nothing was written. This is the same as app-permissions-not-accepted.

Retries by itself? No.

branch-exists#

What you see. "That branch already exists". Every branch name from ulika/setup upwards is taken.

Fix. Delete or rename one of the ulika/setup... branches in the repository, then try again.

Retries by itself? No.

repository-changed#

What you see. "This repository changed since we read it". New commits landed on the default branch after Ulika read it, so the diff no longer matches your code.

Fix. Read the repository again, then review the connector. This is the browser version of source-changed.

Retries by itself? No.

unsupported-framework#

What you see. "Ulika can't install on this site's setup yet. It supports React sites built with Vite or Create React App, and Next.js App Router sites." Nothing was written to your repository.

Fix. None on Ulika's side yet: the CLI cannot install on this setup either. Pick another repository, or delete the project this attempt left behind (Delete project on its page).

unsupported-layout#

What you see. "We could not find where to add the editor bridge". Ulika could not find a root layout with a <body> element.

Fix. Point the CLI at the project, or report the layout's shape.

nothing-to-write#

What you see. "This repository is already connected". The repository already carries this version of the connector. In ulika connect this becomes connector-already-installed or continues to verification if it can be accounted for.

not-imported#

What you see. "Import this website before installing the connector". The connector includes the discovered bindings, so the project must exist first.

Fix. Complete the import step, then install the connector.

preview-not-verified#

What you see. "The preview is not confirmed yet". Ulika has not read the connector back off a deployed preview, so it will not merge.

Fix. Wait for the preview and use Check again, or merge the pull request yourself.

preview-build-failed#

What you see. "The preview build failed". Clicking Activate did not merge anything, and the preview card shows Open the build log.

Fix. Open the build log, fix the error, then use Check again. Ulika activates only a build your host did not report as failed.

not-approved#

What you see. "This needs an explicit approval". Use the buttons on the page.

vercel-required#

What you see. "Connect Vercel to finish". This connector reads published content while your site builds, so it needs a build token on your Vercel project. Nothing was written.

Fix. Connect Vercel, then create the pull request. See Vercel problems.

vercel-failed#

What you see. "Vercel needs attention". Vercel refused a step Ulika needs before it can create the branch. Nothing was written to your repository.

Fix. Check the Vercel connection card on the page. The sentence shown names the cause, which is one of the items in Vercel problems.

build-command-missing#

What you see. "We could not find how this site builds". Ulika wraps your existing build command, and the project has neither a build script nor a build command on its hosting project.

Fix. Add a build script in package.json (or a build command on the hosting project), then try again.

connector-conflict#

What you see. "This repository already has conflicting configuration". The repository carries a connector for another project, its own CMS endpoint, a file of its own where Ulika's connector goes (for example app/cms/content.json/route.ts when the site uses JavaScript, which the message names), or a vercel.json Ulika cannot read.

Fix. Resolve the conflict first (Ulika will not overwrite it). In ulika connect this appears as repository-connected-elsewhere or connector-foreign-files.

pending-changes#

What you see. "Publish or discard your pending edits first". See collections-or-pending-drafts.

collections-unsupported#

What you see. "This site's collections need a different connector". The build-time connector cannot deliver collections yet. Use the CLI or the Next.js runtime connector.

wrong-root-directory#

What you see. "The hosting project builds from a different folder". Fix the Root Directory setting on the hosting project so it matches the folder where the site's code lives, then try again.

unreadable-config#

What you see. "Ulika could not read a configuration file it would have to change". A file the connector must change (vercel.json, ulika.config.json or something in .ulika/) is too large, binary or not a regular file. Ulika will not create a replacement over it.

Fix. Fix or remove that file, then try again.

abandoned#

What you see. "The pull request was closed without merging". See pull-request-closed. Create a new pull request to try again.

preview-private#

What you see. "Ulika can't open this preview because it is private". Ulika could not read the preview because it asks for a sign-in.

Fix. Click Activate again to merge anyway. Ulika checks your live site right after merging and undoes its change if the live build fails.

Notices on a connected site#

After a connector is live, the connect screen can show one of these notices:

NoticeWhat it meansWhat to do
Deploy hook missingThe connector is active, but Ulika could not set up the deploy hook that rebuilds the site. Content published in Ulika will not go live until a hook exists.Add a deploy hook in your hosting settings.
Source changedFiles the connector binds to changed on your default branch. Merging would stop your next build.Re-scan the site in Ulika and create a new connector pull request.
Pull request closedThe connector pull request was closed without being merged.Create a new one.
RevertedYour host's production build failed after the connector was merged, so Ulika reverted its own change.Check the build log, then create a new connector pull request.
Production build failedYour host reports that production failed after the merge. Your live site keeps serving the previous deployment.Open the build log on your host.

Was this page helpful?

PreviousWebsite codeNext Vercel problems

On this page

  • Where you see these
  • How retries work
  • Choosing the repository
  • ambiguous-repository
  • repository-not-in-installation
  • installation-access
  • app-permissions-not-accepted
  • reapproval-required
  • this-is-ulika
  • repository-connected-elsewhere
  • connector-foreign-files
  • Reading the repository and installing the connector
  • unsupported-or-too-large
  • collections-or-pending-drafts
  • content-conflict
  • connector-already-installed
  • project-deleted
  • Your hosting
  • vercel-not-git-linked
  • vercel-not-connected
  • vercel-wrong-account
  • vercel-token-invalid
  • vercel-unavailable
  • vercel-project-conflict
  • Builds and previews
  • build-failed
  • build-slow
  • build-unobservable
  • preview-protected
  • preview-unreadable
  • Pull request and your live site
  • pull-request-awaiting-merge
  • branch-protection
  • pull-request-closed
  • connector-language-changed
  • head-moved
  • source-changed
  • production-proof-missing
  • production-build-failed
  • production-revert-failed
  • production-unverifiable
  • Whole-batch reasons
  • expansion-failed
  • Failed runs
  • credential-revoked
  • internal-error
  • framework-unsupported
  • repository-id-unknown
  • Reasons that begin with connector-, connect-, preflight-, github-, discovery- or import-
  • Connector failure reasons in the browser
  • permission-missing
  • branch-exists
  • repository-changed
  • unsupported-framework
  • unsupported-layout
  • nothing-to-write
  • not-imported
  • preview-not-verified
  • preview-build-failed
  • not-approved
  • vercel-required
  • vercel-failed
  • build-command-missing
  • connector-conflict
  • pending-changes
  • collections-unsupported
  • wrong-root-directory
  • unreadable-config
  • abandoned
  • preview-private
  • Notices on a connected site
Ulika documentationFAQ · CLI reference · Terms · Privacy