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.)

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.