Troubleshoot indexing

Overview

This guide helps you fix common issues that stop documentation from generating in Moxie Docs. Use it if pages are missing, an indexing job seems stuck, or you see permission or subscription errors. Work through the sections that match what you’re seeing.

Before you start

• You can sign in to the Marketing site using Sign in with GitHub.
• You have access to your workspace Dashboard.
• Your GitHub account can install apps on the target repository, or you can ask a repository admin to do it.
• You can view Billing/Subscription in the Dashboard, or ask a workspace admin to check it.

Repository does not appear in Moxie

You’ve signed in but can’t find the repository you want to connect. This usually means the GitHub App isn’t installed for that repo or the account you used doesn’t have access.

1. Sign in to the Marketing site and choose Sign in with GitHub.
2. Open the Dashboard and follow the first‑run prompts to select/install the GitHub App.
   • Choose the GitHub organization and repositories you want Moxie Docs to access.
   • If you don’t see the organization, switch accounts in GitHub or ask an org admin to grant access.
3. Refresh the Dashboard and select the repository. If it still doesn’t appear, confirm you have read access to the repo in GitHub.

Indexing never starts

You clicked into a repository but no pages generate and no job appears to run. This can happen if your trial or subscription isn’t active.

1. Open Dashboard → Billing/Subscription.
2. Start your 14‑day trial or complete checkout to begin a paid plan in Stripe Checkout.
3. Wait a moment for the status to update; webhooks keep your subscription in sync. Then return to the repository and start indexing again from Docs.

Indexing is stuck or very slow

A job shows as running for a long time and pages don’t update. Network delays or a transient GitHub issue may pause progress.

1. Wait a few minutes, then refresh the Docs page for the repository.
2. Retry the indexing job from the Docs view if available.
3. Confirm your subscription is active in Billing/Subscription. If inactive, restore it and then retry indexing.

Permission error when connecting GitHub

You see a message that Moxie Docs can’t read the repository or open docs‑only PRs. This means the GitHub App doesn’t have permission on that repo.

1. Open the Dashboard and select the repository flow again to manage the GitHub App.
2. Update the installation to include the specific repository, or switch to an account with admin rights to install the app.
3. Return to the Docs page and start indexing again.

Pages are missing after indexing

Indexing completes, but expected topics don’t show up in the Docs collections or search.

1. Refresh the Docs page and browse the collections (for example, Get started, Architecture, Backend) to verify where pages landed.
2. Run indexing again from the Docs view to pick up recent changes.
3. Check with a teammate that the source content exists in the connected repository branch you intended to index.

Search shows outdated content

You find a page, but the information looks old. The repo may have changed since the last indexing run.

1. Open the Docs page for the repository.
2. Trigger a new indexing job to regenerate pages.
3. Verify the page shows updated content and is searchable again.

Docs-only PRs are not appearing in GitHub

You expect a docs‑only PR but nothing shows up. This can be caused by missing app permissions or an inactive subscription.

1. Confirm in Dashboard → Billing/Subscription that your trial or plan is active.
2. Revisit the GitHub App installation from the Dashboard first‑run flow and include the target repository.
3. Retry indexing from the Docs page and then check the repository’s Pull Requests in GitHub.

Still need help

• Recheck: you are signed in with the correct GitHub account, the GitHub App is installed for the exact repository, and your subscription in Billing/Subscription is active.
• If problems continue, contact your workspace admin to confirm permissions or to adjust the GitHub App installation. If your admin can’t resolve it, share screenshots of the Dashboard and any error messages when you contact support.