> ## Documentation Index
> Fetch the complete documentation index at: https://trunk-4cab4936-sam-gutentag-merge-queue-config-issues-panel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common Trunk Merge Queue issues and how to fix them, including permission errors, stuck PRs, and missing status checks.

## Configuration issues panel

When Trunk detects a ruleset or merge-instance setting that will cause PRs to fail or behave unexpectedly, an **Issues** tab appears in the Merge Queue navigation. Each issue card names the affected ruleset, explains the problem, and tells you what to change. The tab only appears when problems exist.

Common issues detected:

* **Trunk on bypass list for a rules-enforcement ruleset.** If Trunk Merge is on the bypass list for a ruleset that enforces required reviews or status checks, PRs can enter the queue before those gates are satisfied. Remove Trunk from the bypass list; Trunk only needs bypass permission for branch update and push protection rules.

## If your test PR doesn't merge automatically

<Info>
  Visit [Trunk Support](../../setup-and-administration/support) for additional assistance or to contact the support team.
</Info>

Start here if a PR you submitted isn't merging:

* **Check the status comments for the PR in** the [Trunk Dashboard](https://app.trunk.io/) to see what it's waiting for
* **Stuck in "Queued"**: Usually means branch protection rules haven't passed (missing required status checks or code review) or there are merge conflicts. If the status looks correct but the PR still won't enter the queue, try [removing](/merge-queue/using-the-queue/handle-failed-pull-requests#manually-restarting-failed-pull-requests) and re-adding by commenting `/trunk merge` again on the PR.
* **Fails when attempting to merge**: Check that squash merges are enabled for your repository in GitHub settings (`Settings > General > Allow squash merging`). Trunk Merge Queue requires squash merges to be enabled.
* **"Permission denied" errors**: Review the [Branch Protection](/merge-queue/getting-started/configure-branch-protection#configure-branch-protection-rules) guide to make sure `trunk-temp/*` and `trunk-merge/*` branches aren't protected by wildcard rules like `*/*`.
* **Status checks not running**: Verify your CI is configured to run on draft PRs (or `trunk-merge/**` branches if using push-triggered mode). See the [Branch Protection](/merge-queue/getting-started/configure-branch-protection#configure-branch-protection-rules) guide for details.

## Common errors and stuck states

<AccordionGroup>
  <Accordion title="&#x22;Permission denied on trunk-merge/* branch&#x22;">
    **Cause:** Branch protection rules are applying to Trunk's temporary branches.

    **Solution:** Follow the "Exclude Trunk's Temporary Branches" section above to make sure `trunk-temp/*` and `trunk-merge/*` are not protected.
  </Accordion>

  <Accordion title="Pull request stuck as &#x22;Queued&#x22; in the queue">
    **Cause:** Required status checks are not completing or not configured correctly.

    **Solution:**

    * Click on the pull request in the Trunk Dashboard to see which checks it's waiting for
    * Verify those checks are running in your CI provider
    * If using Push-triggered mode, make sure the check names in `trunk.yaml` exactly match your CI job names
  </Accordion>

  <Accordion title="Required status checks not running">
    **If using Draft PR mode:** Verify your CI workflows are triggered by pull requests (including draft pull requests).

    **If using Push-triggered mode:**

    * Verify your CI workflows trigger on pushes to `trunk-merge/**` branches
    * Check that the workflows actually ran in your CI provider's interface
    * Make sure the `trunk-io` bot has permission to push to create these branches
  </Accordion>
</AccordionGroup>