fix: improve error messages for catalog download failures

[maxandersen]

Fixes #2559

When a catalog download fails and authentication was in play, users get an unhelpful "Unknown catalog" error with no clue that their token or credentials might be the problem.

What changed

NetUtil.describeAuthMethod(url) checks which auth method (if any) would apply for a given URL, using the same priority order as addAuthHeaderIfNeeded: GITHUB_TOKEN, GITLAB_TOKEN, URL credentials, .netrc, JBANG_AUTH_BASIC_*. Returns a human-readable label or null.

ImplicitCatalogRef.tryDownload() now calls describeAuthMethod on failure and warns when credentials were involved:

[jbang] [WARN] Could not download catalog from https://github.com/quarkusio/jbang-catalog/blob/HEAD/jbang-catalog.json. Authentication via GITHUB_TOKEN was used but may be expired or invalid. Try updating or removing the credentials.

This works for all auth methods, not just GITHUB_TOKEN.

Catalog.findImportedCatalogsWith() now passes both the exception message and the Throwable to verboseMsg, so the error reason is visible without --verbose and stack traces still print when verbose is on.

Tests cover .netrc, URL credentials, priority ordering, null returns for unmatched URLs, and invalid input.

See #2560 for a follow-up to include attempted download URLs in the "Unknown catalog" error message itself.

Summary by CodeRabbit

• New Features
  • Improved authentication detection for remote downloads, with clearer guidance when credentials are being used.
• Bug Fixes
  • Download failures now show more helpful warnings when authentication may be expired or invalid.
  • Error logging is more informative, making failures easier to diagnose.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4733acb3-fb2d-4be7-ab0d-bb1b63c81c3e

📥 Commits

Reviewing files that changed from the base of the PR and between 004f649 and cf5dd94.

📒 Files selected for processing (4)

• src/main/java/dev/jbang/catalog/Catalog.java
• src/main/java/dev/jbang/catalog/ImplicitCatalogRef.java
• src/main/java/dev/jbang/util/NetUtil.java
• src/test/java/dev/jbang/util/TestDescribeAuthMethod.java

---

📝 Walkthrough

Walkthrough

This PR improves catalog error diagnostics: exception logging in Catalog now includes the exception object and message; NetUtil gains a describeAuthMethod utility that identifies which authentication source (token, URL userinfo, .netrc, basic auth) applies to a URL; ImplicitCatalogRef uses it to warn about possibly expired credentials on download failure; new tests cover the utility.

Changes

Auth-aware catalog download error reporting

Layer / File(s)	Summary
Verbose exception logging src/main/java/dev/jbang/catalog/Catalog.java	Catch block logging now includes the exception message and passes the exception object to Util.verboseMsg.
Auth-method detection utility src/main/java/dev/jbang/util/NetUtil.java	Refactors host-detection into private helpers and adds describeAuthMethod(String url), which returns a description of the auth source (host token env var, URL userinfo, .netrc, or global basic-auth env vars) or null.
Wiring into download failure path src/main/java/dev/jbang/catalog/ImplicitCatalogRef.java	On download failure, calls NetUtil.describeAuthMethod(url) and logs a warning about potentially expired/invalid credentials when an auth method is detected.
Unit tests src/test/java/dev/jbang/util/TestDescribeAuthMethod.java	Adds tests covering URL credentials, .netrc machine/default entries, no-match/no-auth cases, invalid URLs, and credential precedence.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related issues

• catalog issue does not give good user/error info #2559: Directly addresses the issue's request to log the underlying exception with --verbose and to hint about GITHUB_TOKEN usage during download failures.
• feat: track implicit catalog resolution failures for better error messages #2560: Touches the same implicit catalog resolution/error-reporting flow in ImplicitCatalogRef and Catalog.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}