Troubleshooting GitHub Export and Import

Below are the most common issues with GitHub Export and Import and how to resolve them.

I see an upgrade prompt when I open Pull from GitHub

GitHub Import requires an active paid subscription. If you are on a free plan and open Pull from GitHub from the project settings More menu, Caffeine shows the message "An active paid subscription is required to pull from GitHub." along with an option to upgrade. Once you have an active paid subscription, you can use GitHub Import to pull code from your connected repository into your Caffeine project.

The "Push to GitHub" option is not visible

GitHub Export is not available on all accounts by default. If you don't see the Push to GitHub option in your project settings menu, the feature may not be enabled on your account yet. Contact support and we can enable it for you.

I started a GitHub Import but nothing seems to be happening

Imports run in the background. After clicking Import, Caffeine posts a message in your chat to confirm the import has started. The process can take a few minutes. You can keep working while it runs and Caffeine will notify you in chat when it finishes or if it encounters a problem. There is no need to stay on the import screen.

My GitHub Import failed with an error message

If the import fails, Caffeine shows an error message explaining what went wrong. Common causes include:

• The git ref you entered does not exist in the repository (check the branch name, tag, or commit hash for typos).
• The repository is no longer accessible (it may have been deleted or the Caffeine GitHub App may have been uninstalled).
• Your subscription has lapsed — an active paid subscription is required to use GitHub Import.

After reviewing the error, click Back to return to the import form and try again, or click Close to dismiss the dialog.

The "Push to GitHub" option is greyed out or unavailable

GitHub Export requires your project to have at least one draft — a version of your app that the AI has built. If your project has no draft yet (for example, you have just created the project but haven't run a build), the export option will be unavailable.

To resolve this, send a message in the chat to start a build. Once the AI has generated and deployed a draft of your app, the export option will become available.

The GitHub authorization window was blocked or timed out

When you click Sync to GitHub, Caffeine opens a popup window and waits for you to complete the GitHub App installation. If the popup is blocked or the installation is not completed in time, the connection attempt will fail with the message: "GitHub App installation timed out. Please try again and follow the installation instructions in the pop up window. Disable any browser pop up blockers."

If this happens:

1. Check your browser's address bar for a blocked popup notification and allow the popup from there.
2. If you use an ad-blocker or browser extension that blocks popups, temporarily disable it and try again.
3. Once popups are allowed, click Sync to GitHub again and complete the installation promptly in the popup window.

I closed the GitHub authorization window before finishing

If you close the GitHub App installation popup before completing the authorization, Caffeine detects this and shows an error: "GitHub application Install & Authorize aborted by user."

This is expected. To connect your GitHub account, the installation must be completed in full — closing the window partway through cancels the process.

To try again, open Push to GitHub from your project settings and click Sync to GitHub to restart the authorization flow from the beginning.

I authorized GitHub but nothing happened

After authorizing, the GitHub window should close automatically and your first export should begin. If the window closed but no export started:

1. Refresh the page and open Push to GitHub again.
2. If your account is now shown as connected, click Save Changes to GitHub to trigger the export manually.
3. If the connection still shows as unlinked, try the authorization flow again.

My export is taking a long time

Exports are processed asynchronously. After you click Save Changes to GitHub, Caffeine queues the export and processes it in the background — this typically takes a few minutes. You don't need to stay on the page while it runs. You will receive a chat message when the export completes, or if it encounters a problem.

If no commit appears in your GitHub repository after 10 minutes and you have not received a completion message in chat, try exporting again.

I get an error saying "No GitHub installation found"

This means Caffeine can't find a connected GitHub account for your project. This can happen if:

• You revoked or uninstalled the Caffeine GitHub App from your GitHub account settings.
• The connection was made under a different account.

To fix this, go to Push to GitHub in your project settings and reconnect your GitHub account by following the authorization flow again.

The export says it succeeded but I don't see the commit in GitHub

Exports create commits on the main branch. Make sure you're looking at the correct branch in GitHub (some repositories default to showing a different branch).

If the AI detected that no files changed between the current build and the previous export, no commit is created — this is expected behavior and is not an error.

The Import button is disabled

GitHub Import is available to paid subscribers only. If the Import button in the Pull from GitHub panel is greyed out and you see the message "An active paid subscription is required to pull from GitHub.", your account is on the free (Basic) plan. Upgrade to a paid subscription to enable the Import button.

I can't create a private repository

Private repository creation requires an active paid subscription. If the Private option is greyed out in the export dialog, upgrade your plan and try again.

My repository name was rejected

Repository names can only contain lowercase letters, numbers, and hyphens, and must be 100 characters or fewer. Names with uppercase letters, spaces, or special characters (other than hyphens) are not accepted by GitHub.

I accidentally connected the wrong GitHub account

At the moment, you can disconnect and reconnect your GitHub account by revoking the Caffeine GitHub App from your GitHub account settings (GitHub → Settings → Applications → Authorized GitHub Apps or Installed GitHub Apps), and then reconnecting from within Caffeine. Contact support if you need further help.

Exports keep failing even though I'm logged into GitHub

If you have already authorized GitHub but exports consistently time out or fail, the GitHub App installation may be in a broken state. This can happen if the initial authorization completed partially or if browser settings interfered with the process.

To fix this:

1. Go to your GitHub settings: Settings → Applications → Installed GitHub Apps (or visit github.com/settings/installations directly).
2. Find caffeine-ai in the list and click Uninstall.
3. Return to Caffeine, open Push to GitHub in your project settings, and click Sync to GitHub to start a fresh authorization.
4. When the GitHub popup appears, complete the installation promptly — the authorization window times out after 60 seconds.

This resets the connection cleanly and resolves most persistent export failures.

The export failed partway through

If a file in your project fails to load, Caffeine skips that file and continues with the rest. In rare cases this can result in an incomplete repository. If you suspect files are missing, try triggering another export — subsequent exports push a new commit with the full current state of your project.

The GitHub Import button is disabled and shows an "AI operation is in progress" message

If you open the GitHub Import panel while Caffeine is actively building your app, the git ref field and the Import button are both disabled, and a message reads "AI operation is in progress. Try again later after it finishes."

This is intentional. Importing code from GitHub while a build is running could conflict with the changes the AI is making at the same time, leading to unpredictable results. Wait for the current build to finish — you will see the build complete in the chat — then return to the GitHub Import panel and try again.

My GitHub import failed and I don't know why

When a GitHub import fails, Caffeine shows a message explaining the specific reason. Common reasons include:

• File too large — A single file exceeds the size limit allowed for import. The error names the file and the limit (for example: File 'frontend/public/assets/video.mp4' is too large: 52428800 bytes (max 10485760).).
• Too many files — The repository contains more files than Caffeine can import in one operation (for example: Too many files: 5200 (max 5000).).
• Total size exceeded — The combined size of all files exceeds the limit (for example: Total size 104857600 bytes exceeds limit of 52428800 bytes.).
• Repository not found — The repository could not be accessed (for example: Repository owner/name not found.). Check that the repository exists and that the Caffeine GitHub App has permission to read it.
• Ref not found — The branch, tag, or commit hash you entered does not exist in the repository (for example: Ref 'feature-x' not found.). Check the ref for typos.
• Invalid project structure — Required Caffeine files are missing from the repository. The error message lists what is missing — see the "Project structure" section below.

Read the error message carefully — it identifies exactly what went wrong. If the message says "GitHub API error", there may be a temporary problem with GitHub's service; wait a few minutes and try again.

Project structure is important for GitHub Import

The repository must follow the standard Caffeine project structure for the import to succeed. The expected layout is:

caffeine.toml
mops.toml
src/
  frontend/
    caffeine.toml
    package.json
  backend/
    caffeine.toml

If required files are missing, the import will fail with an "Invalid project structure" error and Caffeine will list exactly which files need to be added. Add the missing files to your repository and try again.

GitHub Import progress and errors

When you trigger a GitHub import, Caffeine runs it in the background and posts status messages directly in your project chat:

• Importing [ref] from [repository]... — the import has started.
• Import from GitHub from [repository] complete, draft version [N] created. — the import finished successfully and a new draft was created.
• An error message describing what went wrong if the import fails. Common error messages include:
  • No GitHub token found. Please connect your GitHub account. — your GitHub account is not connected. Reconnect it from the project settings.
  • Repository [owner]/[name] not found. — check that the repository name is correct and that the Caffeine GitHub App has access to it.
  • Ref '[ref]' not found. — the branch, tag, or commit hash you entered does not exist.
  • Too many files: [count] (max [limit]). — the repository contains more files than Caffeine can import.
  • File '[path]' is too large: [size] bytes (max [limit]). — one or more files exceed the per-file size limit.
  • Total size [size] bytes exceeds limit of [limit] bytes. — the combined size of all files is too large.
  • Repository tree is too large (truncated by GitHub). — GitHub returned an incomplete file list because the repository is very large.
  • GitHub API error. — a temporary problem with GitHub's service; wait a few minutes and try again.

If you do not see any of these messages after triggering an import, check that you are looking at the correct project's chat. If the chat is empty, try refreshing the page.

My GitHub import failed

If a GitHub import fails, Caffeine now shows the specific reason returned by the service — for example, a message explaining why the import could not be completed. Read the error message carefully, as it will usually tell you what went wrong.

Common causes include:

• The repository or branch you specified does not exist or is not accessible with the connected GitHub account.
• The Caffeine GitHub App does not have permission to read the repository (this can happen with private repositories owned by an organization).
• A temporary service error occurred.

If the error message does not make the problem clear, contact support and include the exact text of the error — it will help us diagnose the issue faster.