errors: repo-scoped 404s name neither forge nor slug nor config source - "API error 404: not found" is a puzzle when the real problem is a forge mismatch #199

New issue

Closed

opened 2026-07-17 14:31:00 +00:00 by hexajon · 0 comments

hexajon commented

2026-07-17 14:31:00 +00:00

(Migrated from codeberg.org)

Repro

In the #197 split-brain repo (local madtea.url -> forge Y from repo config, origin -> forge X):

madtea issue list
# -> Error: API error 404: not found

That one line is everything the user gets. It does not say which forge was contacted, which owner/repo slug was requested, or where the URL came from. The user's actual next steps in the live session were: run auth login (no change), run madtea update (no change), give up and hand the transcript to an agent - which had to read clone.go, config.go, and setup.go to discover the madtea.url override. Every piece of information needed to self-diagnose was known to the process at error time and thrown away.

Expected

A repo-scoped 404 names the full request context and walks the user to the fix:

Error: repo sixfold_space/madtea not found on gitea.example (GET /repos/sixfold_space/madtea/issues)
  forge URL:  https://gitea.example  (from repo config madtea.url)
  repo slug:  sixfold_space/madtea   (from origin remote)
  note: your origin remote points at codeberg.org, but madtea.url overrides the forge to gitea.example.
  If codeberg.org is the right forge: git config --unset madtea.url   (then madtea auth login if needed)

Concretely:

Every repo-scoped 404 carries forge host + owner/repo slug + the resolution source of each ("repo config" / "origin remote" / "global config" / "environment") - the same source labels auth whoami already computes in GetCredentialsWithSource.
When the resolved forge host differs from the origin remote's host, SAY SO in the error - that single line converts the #197 class from a code-reading exercise into a one-command fix. Detection is cheap: both hosts are already resolved in-process.
This extends the existing enrichment work (#173's typed unknown-owner errors, #185's GetRepoByName marker, the owner_repo hint from RepoOverride) from "name the missing entity" to "name the whole request context and the likely cause".

House principle: loud, explicit errors with next steps - never a bare status code the user has to reverse-engineer.

#197 - the incident; its expected-behavior list fixes the cause, this issue fixes the diagnosability.
#185 (open), #173 (closed) - existing 404 enrichment thread.
#60 (closed) - same principle for update failures.

## Repro In the #197 split-brain repo (local `madtea.url` -> forge Y from repo config, origin -> forge X): ``` madtea issue list # -> Error: API error 404: not found ``` That one line is everything the user gets. It does not say which forge was contacted, which owner/repo slug was requested, or where the URL came from. The user's actual next steps in the live session were: run `auth login` (no change), run `madtea update` (no change), give up and hand the transcript to an agent - which had to read clone.go, config.go, and setup.go to discover the madtea.url override. Every piece of information needed to self-diagnose was known to the process at error time and thrown away. ## Expected A repo-scoped 404 names the full request context and walks the user to the fix: ``` Error: repo sixfold_space/madtea not found on gitea.example (GET /repos/sixfold_space/madtea/issues) forge URL: https://gitea.example (from repo config madtea.url) repo slug: sixfold_space/madtea (from origin remote) note: your origin remote points at codeberg.org, but madtea.url overrides the forge to gitea.example. If codeberg.org is the right forge: git config --unset madtea.url (then madtea auth login if needed) ``` Concretely: 1. Every repo-scoped 404 carries forge host + owner/repo slug + the resolution source of each ("repo config" / "origin remote" / "global config" / "environment") - the same source labels `auth whoami` already computes in `GetCredentialsWithSource`. 2. When the resolved forge host differs from the origin remote's host, SAY SO in the error - that single line converts the #197 class from a code-reading exercise into a one-command fix. Detection is cheap: both hosts are already resolved in-process. 3. This extends the existing enrichment work (#173's typed unknown-owner errors, #185's GetRepoByName marker, the owner_repo hint from RepoOverride) from "name the missing entity" to "name the whole request context and the likely cause". House principle: loud, explicit errors with next steps - never a bare status code the user has to reverse-engineer. ## Related - #197 - the incident; its expected-behavior list fixes the cause, this issue fixes the diagnosability. - #185 (open), #173 (closed) - existing 404 enrichment thread. - #60 (closed) - same principle for update failures.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#199

No description provided.

Rows
Columns