> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lanesync.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common LaneSync issues and fixes — sync, stuck milestones, rulesets, and deploy gates.

Solutions for common issues on the hosted SaaS at [lanesync.dev](https://lanesync.dev). Self-hosted customers should also check container logs.

## Dashboard shows no milestones

<AccordionGroup>
  <Accordion title="Symptoms" id="no-milestones">
    Dashboard empty after installing the GitHub App.
  </Accordion>

  <Accordion title="Fixes">
    1. Click **Refresh** to trigger sync
    2. Verify the GitHub App is installed on the repository (GitHub → Settings → Applications)
    3. Confirm milestones exist in GitHub with linked issues
    4. Self-hosted: check backend logs for webhook delivery errors
  </Accordion>
</AccordionGroup>

## Milestone stuck in PLANNING

<AccordionGroup>
  <Accordion title="Symptoms" id="milestone-stuck-in-planning">
    Stage does not advance after creating milestone and issues.
  </Accordion>

  <Accordion title="Fixes">
    **All milestone issues must have assignees.**

    Open each issue in GitHub → Assign a team member → Refresh dashboard.
  </Accordion>
</AccordionGroup>

## Milestone stuck in DEVELOPMENT

<AccordionGroup>
  <Accordion title="Symptoms">
    Development stage shows blocking items after merges.
  </Accordion>

  <Accordion title="Fixes">
    1. Close all milestone issues via **merged** PRs (not manual close without merge)
    2. Ensure required CI checks pass on `main` — names must match `sdlc.yaml` `development.required_checks`
    3. Cut release branch (e.g. `release/v1.0.0`) unless using trunk-based mode
    4. Check stage details for which checks are marked blocking
  </Accordion>
</AccordionGroup>

## Milestone stuck in TESTING

<AccordionGroup>
  <Accordion title="Symptoms">
    Testing stage blocked after release branch created.
  </Accordion>

  <Accordion title="Fixes">
    1. Verify CI ran on the release branch
    2. Fix failing checks listed in `testing.required_checks`
    3. Confirm `branch_pattern` in `sdlc.yaml` matches your branch name (`release/*` vs `release/**`)
  </Accordion>
</AccordionGroup>

## Rulesets not created

<AccordionGroup>
  <Accordion title="Symptoms">
    No branch protection after bootstrap.
  </Accordion>

  <Accordion title="Fixes">
    1. GitHub App needs **Administration: Read & Write** (full tier)
    2. Re-approve permissions on the installation
    3. Re-run repo setup wizard or push `sdlc.yaml` to trigger `ensureRulesets()`
  </Accordion>
</AccordionGroup>

## Phantom BLOCKING badges

<AccordionGroup>
  <Accordion title="Symptoms">
    Checks show blocking but workflow succeeded, or unknown check names appear.
  </Accordion>

  <Accordion title="Fixes">
    Stale check names in DB cache. Update `required_checks` in `sdlc.yaml` to match current GitHub Actions job names and push to default branch. Webhook re-syncs rulesets and milestones.
  </Accordion>
</AccordionGroup>

## Production deploy blocked

<AccordionGroup>
  <Accordion title="Symptoms">
    Deploy workflow refuses to promote.
  </Accordion>

  <Accordion title="Fixes">
    1. Evidence PR must be approved (`evidencing.required_reviewers`)
    2. Deploy gate must return `can_deploy: true` (requires CI auth — OIDC token or `LANESYNC_API_KEY`):
       ```bash theme={null}
       curl -H "Authorization: Bearer $TOKEN" \
         "https://lanesync.dev/api/milestones/check?version=v1.0.0&repo=my-repo"
       ```
    3. Milestone must be in **DEPLOYMENT** stage with all prior gates passed
  </Accordion>
</AccordionGroup>

## SDLC Enforce always failing

See [SDLC Enforce action](/reference/sdlc-enforce-action) for action-specific failures.

## Still stuck?

<CardGroup cols={2}>
  <Card title="FAQ" icon="circle-help" href="/reference/faq">
    Common questions about SaaS vs self-hosted.
  </Card>

  <Card title="Contact support" icon="mail" href="mailto:support@lanesync.dev">
    Reach the LaneSync team.
  </Card>
</CardGroup>