# Troubleshooting

Source: /docs/troubleshooting

If you hit a message that is not here, or a fix does not work, see [support](/docs/support).

## Importing [#importing]

* **"Connect GitHub before importing a private repository."** — Click **Connect GitHub** on the GitHub tab first.
* **"GitHub installation not found. Reconnect your account."** — Access to the GitHub App was removed. Reconnect from the GitHub tab.
* **"GitHub is temporarily unavailable. Try again shortly."** — A GitHub outage. Retry in a few minutes.
* **"No repositories found."** — The GitHub App has access to no repositories. Click **Add repositories** and grant it access on GitHub.
* **"File exceeds the 100 MB limit."** — Trim the ZIP; exclude `node_modules`, `.git` and build output.
* **"The uploaded file is not a valid ZIP archive."** — Re-create it as a real ZIP and upload again.
* **"Import expired or not found. Upload the ZIP again."** — Upload links are short-lived. Re-upload.

## Naming and address [#naming-and-address]

* **"App name is required." / "App name must be at most 100 characters."** — Fix the name.
* **"Enter a valid repository URL"** — Use a full repository URL, like `https://github.com/org/repo`.
* **"This subdomain is already taken." / "This subdomain is reserved."** — Pick another subdomain.

## Readiness scan [#readiness-scan]

* **"The readiness scan found a problem that blocks this deploy. Open the scan to see what it found, fix it, then deploy again."** — Work the [fix loop](/docs/concepts/readiness-and-fixes): apply the fix prompt, push or re-upload, re-scan.
* **"Our check could not run" / "Scan failed. Please try again."** — A problem on the platform side. Re-scan in a few minutes; if it persists, contact support.
* **"Checked earlier code"** — Your source changed since the scan. Re-scan so the result matches what would go live.

## Deploying [#deploying]

* **"Run a readiness scan before deploying"** — Deploy is disabled until a scan has run. Run it.
* **"Fix scan findings before deploying"** — The last scan blocked. Clear it, then deploy.
* **"Blocked by the security scan: `{reason}`. Run the readiness scan to see what it found, fix it, and deploy again."** — The build-time security gate refused the source. Open the scan, fix what it names, deploy again.
* **"A deploy is already running. Wait for it to finish, then try again."** — One pipeline runs at a time.
* **"An operation is in progress — wait for it to finish"** — Another change is mid-flight. Wait, then retry.
* **"This app isn't ZIP-based — update its repository instead."** — This app came from GitHub. Push to its branch instead of uploading a ZIP.
* **Deploy failed, with "This may be caused by dedicated database provisioning failing. Contact support if it persists."** — Retry once; if it keeps failing, contact support.

## Branches (GitHub apps) [#branches-github-apps]

* **"That branch is not in the repository any more. Pick one from the list."** — The branch was deleted or renamed. Choose a current one.
* **"This app was uploaded as a file, so there is no repository to pick a branch from."** — Branch settings do not apply to ZIP apps.

## Environment variables [#environment-variables]

* **"Key must start with A–Z or \_ and contain only uppercase letters, numbers, and underscores."** — Rename the key.
* **"This key is reserved by the platform (e.g. PORT, DATABASE*URL, META*\*)."** — Pick another name; that key is injected for you.
* **"Value is required."** — Enter a value.

## Custom domains [#custom-domains]

* **"That doesn't look like a valid domain."** — Enter a full domain, like `shop.example.com`.
* **"This domain is already connected to an app."** — It is used elsewhere on the platform.
* **"This domain doesn't point at our gateway yet. Update its A-record and try again."** — Add or fix the DNS record, wait for it to propagate, then **Check now**.
* **"That's one of our subdomains, so use the subdomain field instead."** — Use the subdomain field.

## Running app [#running-app]

* **"App isn't running — deploy it to see its logs."** — Deploy the app first.
* **"Couldn't load logs. Try refreshing."** — A transient read error. Refresh.
* **"This app was stopped by an admin and can't be restarted. Contact support."** — An administrator suspended it. Reach support.
* **"This action isn't available right now — the app may be mid-deploy."** — Wait for the running operation, then retry.

## Database [#database]

* **"This app has no database yet. Add one in Settings, then deploy."** — Turn on the database in **Settings** and deploy.
* **"This app already has a database, so it can't be taken away. Delete the app if you want its data gone."** — A database, once attached, stays with the app.
* **"A database change is still finishing. Try again in a moment."** — Wait for the change to complete.