Troubleshooting Guide

This guide covers common errors in madtea, their causes, and how to fix them. Error messages are taken directly from the codebase.

1. Configuration Errors

not configured - run 'madtea auth login' first

Cause: No Forgejo/Gitea URL or token found in environment variables or git config.

Recovery:

madtea auth login           # Interactive setup for this repo
madtea auth login --global  # Store credentials globally
# Or set environment variables:
export MADTEA_URL=https://forgejo.example.com
export MADTEA_TOKEN=your-token

not configured - run 'madtea auth login' or set MADTEA_URL and MADTEA_TOKEN

Cause: GetConfig() found neither env vars nor git config entries. Same fix as above.

madtea.url not configured / madtea.token not configured

Cause: Git config has a partial setup — URL exists but token is missing, or vice versa.

Recovery: Re-run madtea auth login to set both values.

secure backend "..." unavailable and no plaintext token found — run 'madtea auth login' to reconfigure, or set MADTEA_TOKEN

Cause: The configured credential backend (keychain, pass, or systemd-creds) is not installed or not accessible — or it is reachable but holds no token for this URL/user — and no plaintext madtea.token exists to fall back to.

Recovery:

• Re-login: madtea auth login re-detects the backend and stores the token again.
• macOS keychain: Ensure you are running on macOS with Keychain Access available.
• pass: Install pass (apt install pass / brew install pass) and initialize it (pass init <gpg-id>).
• systemd-creds: Requires systemd ≥ 256 for the per-user path; ensure the host key (or TPM) is accessible. A missing/locked key makes the backend report unavailable.
• Fallback: Re-run madtea auth login --insecure-storage to store the token in plaintext git config instead.

unknown credential backend: <name>

Cause: madtea.credential-backend git config is set to an unrecognized value. Supported values: keychain, pass, systemd-creds.

Recovery:

git config --unset madtea.credential-backend
madtea auth login

cannot parse repo from remote URL: <url>

Cause: The git remote URL could not be parsed to extract owner/repo. The URL format is unrecognized.

Recovery: Verify your remote URL is correct:

git remote get-url origin
# Should look like: https://forgejo.example.com/Owner/repo.git
# or: git@forgejo.example.com:Owner/repo.git

cannot get git remote: ...

Cause: No origin remote is configured, or the command is not running inside a git repository.

Recovery:

git remote add origin https://forgejo.example.com/Owner/repo.git

2. Authentication Errors

API error 401: ...

Cause: The token is invalid, expired, or revoked.

Recovery:

1. Generate a new token at https://<your-gitea>/user/settings/applications.
2. Re-run madtea auth login to store it.

API error 403: token does not have at least one of required scope(s)...

Hint: update your token scopes at <url>/user/settings/applications

Cause: The token is valid but lacks the required API scope for the operation (e.g., write:repository, write:issue, write:organization).

Recovery: Go to the URL in the hint, edit your token, and add the missing scope(s). The error message includes which scope is required.

user API error 403: ... (during setup)

Cause: Token is valid but missing read:user scope. Setup will print OK (limited token) and warn:

Warning: token is missing 'user' scope (read) — some features will be limited

Recovery: This is non-fatal. Add the read:user scope to your token if you want full functionality (e.g., automatic user detection).

3. Git Operation Errors

not a git repository

Cause: The current directory is not inside a git repository.

Recovery:

cd /path/to/your/repo
# or initialize a new repo:
madtea init my-repo --org sixfold_space

no staged changes to commit

Cause: No files are staged. madtea finish and madtea commit require staged changes.

Recovery:

git add <files>
# Then retry your command

no staged changes to commit - stage changes first with madt_add (or 'madtea add'), pass files=[...] to finish, or use --no-commit if already committed

Cause: Same as above, but during madtea finish. If you already committed with git commit, you can skip the commit step.

Recovery:

madtea finish --no-commit "type: description" --summary "..."

no commits to push - you have uncommitted changes: ...

Cause: madtea finish --no-commit was used while the working tree still has uncommitted changes — stage them (madt_add / madtea add) and re-run without --no-commit, or commit them yourself first. When the tree is clean but the branch has no commits ahead of the default, the error is your branch has no commits ahead of <default> - nothing to finish instead (the branch is already merged, or its tip equals the default’s tip).

Recovery: Either commit first, or drop --no-commit:

git add <files> && git commit -m "your message"
madtea finish --no-commit "type: description" --summary "..."

branch "<name>" already exists

Cause: Attempted to create a branch that already exists locally.

Recovery:

git checkout <name>          # Switch to the existing branch
# or delete it first:
git branch -d <name>         # Safe delete (only if merged)
madtea branch -b <new-name> # Create with a different name

uncommitted changes would be overwritten

Cause: madtea checkout cannot switch branches because local changes would be lost.

Recovery:

git stash                    # Stash changes temporarily
madtea checkout <branch>
git stash pop                # Restore changes
# or commit first:
git add . && git commit -m "wip: save progress"

pull refused: you have uncommitted changes on tracked files.

Cause: madtea pull refuses to pull when the working tree is dirty — any staged, unstaged, or conflicted change on a tracked path. This prevents merge conflicts and accidental loss of in-progress work. (Untracked files are not counted; run git status to see what is blocking.) A local branch with no commits yet is an unborn branch. An unborn branch with an empty index is not dirty. This refusal does not apply to it, even when the branch tracks a populated remote. madtea allows the first fast-forward into a fresh checkout.

Recovery:

git stash
madtea pull
git stash pop

merge conflict - resolve and commit

Cause: A merge or pull produced conflicts that need manual resolution. The error message lists the affected files.

Recovery:

# Edit the conflicted files listed in the error
git add <resolved-files>
madtea merge --continue     # or: madtea rebase --continue

rebase conflict - resolve and continue

Cause: A rebase produced conflicts.

Recovery:

# Edit the conflicted files
git add <resolved-files>
madtea rebase --continue
# or abort:
madtea rebase --abort

conflicts remain - resolve and continue

Cause: --continue was used but some files still have unresolved conflicts.

Recovery: Check for remaining conflict markers (<<<<<<<) in the listed files, resolve them, git add, then retry --continue.

Redirect Detection (repo moved/renamed)

Two forms:

Git push redirect:

remote redirected to <url>
Your local remote URL is outdated. Fix with:
  git remote set-url origin <url>
then retry

API redirect:

API redirect 3xx on <endpoint>: repo moved -> Owner/new-name (transfer or rename)
Your local remote URL is outdated. Fix with:
  git remote set-url origin https://forgejo.example.com/Owner/new-name.git
then retry

Cause: The repository was renamed or transferred. Git followed the redirect, but madtea blocks it to prevent silent mismatches between the local remote and the API.

Recovery:

git remote set-url origin <new-url-from-error-message>

4. API Errors

404 on repos whose owner contains a dot (e.g. sixfold.space/...)

Symptom: On some Gitea deployments, single-repo issue subpaths return 404 — and issue lists under-report — for repositories whose owner contains a dot (e.g. sixfold.space/repo). The repo is reachable in the web UI, but madtea issue list / madtea issue get / madt_issues 404 or come back short.

Cause: This is a server-side Gitea quirk, not a madtea bug. madtea permits dots in owner names and builds the standard /repos/{owner}/{repo}/issues/... path; some Gitea versions mishandle the dot in that path (treating it like a file-extension separator).

Workaround: Use the cross-org search endpoint, which carries the owner as a query parameter (/repos/issues/search?owner=...) instead of in the path:

madtea issue search --owner sixfold.space --q "your search"

The MCP equivalent is madt_issues action=search search_owner=sixfold.space.

API error 404: ...

Cause: The requested resource does not exist — wrong repo name, issue number, PR number, or the repo is private and your token lacks access.

Recovery: Verify the resource exists. Check for typos in --repo owner/repo. Ensure your token has the appropriate read scope.

API error 422: ...

Cause: Validation error. The server rejected the request — commonly a duplicate PR (same head/base branch already has an open PR), an invalid label ID, or a missing required field.

Recovery: Read the error body for specifics. For duplicate PRs, close or merge the existing one first.

API error 5xx: ...

Cause: Server-side error on the Forgejo/Gitea instance.

Recovery: Wait and retry. If persistent, check the Forgejo/Gitea server logs or status page.

too many redirects

Cause: The HTTP client hit 10+ redirects, likely a misconfigured URL or authentication loop.

Recovery: Verify madtea.url points to the correct Forgejo/Gitea instance (not a reverse proxy that loops).

5. Finish Workflow Errors

cannot finish from <branch> branch - switch to a feature branch first

Cause: madtea finish was run while on the default branch (e.g., master or main). Finish creates a PR from a feature branch into the default branch, so it cannot operate on the default branch itself.

Recovery:

madtea branch -b my-feature
# make changes, then:
madtea finish "feat: description" --summary "..."

PR creation failed: ...

Cause: The Gitea API rejected the pull request. Common reasons: a PR already exists for this branch, the base branch does not exist, or insufficient permissions.

Recovery: Check the full error message. If a PR already exists:

madtea pr list
madtea pr merge <number>

merge failed: ...

Cause: The PR could not be merged. Common reasons: merge conflicts, branch protection rules, or required reviews not satisfied.

Recovery: Resolve conflicts locally, push, and retry. Or merge manually via the Forgejo/Gitea web UI.

push failed: ...

Cause: The git push was rejected. Possible reasons: remote branch has new commits (needs rebase), branch protection prevents force-push, or authentication failed.

Recovery:

madtea pull --rebase
# Resolve any conflicts, then retry finish

failed to return to <branch>: ...

Cause: After merging the PR, madtea finish could not switch back to the default branch. Usually caused by uncommitted changes in the working tree.

Recovery: This is non-fatal — the PR was already merged. Manually switch:

git checkout master

6. Labels & Milestones

unknown label "<name>"[ — did you mean "<suggestion>"?]; available labels: <list>

Cause: The label name passed to an issue or PR command does not match any label in the repository. Label names are case-sensitive.

If the typo is close to an existing label (measured by Levenshtein edit distance), the error will suggest the closest match. A match is accepted when its edit distance is at most half the input length (d <= len/2); a small-input floor means very short names tolerate at most a single-character typo. Very different names won’t produce a suggestion.

Recovery:

madtea labels list                          # See available labels
madtea labels list --repo owner/repo        # For a different repo

unknown label ID <number>; available labels: <list>

Cause: A numeric label ID was passed that does not exist in the repository. The error lists the available labels.

Recovery: Same as above — list labels to find the correct ID.

7. HTTP Status Code Reference

These status codes come from the Forgejo/Gitea API and are prefixed with API error <code>: or API redirect <code>: in madtea error messages.