Skip to content

fix(ux): improve error messages for artifact mismatches and missing release branches#750

Merged
BYK merged 2 commits intomasterfrom
fix/improve-error-messages
Feb 12, 2026
Merged

fix(ux): improve error messages for artifact mismatches and missing release branches#750
BYK merged 2 commits intomasterfrom
fix/improve-error-messages

Conversation

@BYK
Copy link
Member

@BYK BYK commented Feb 12, 2026

Summary

Two UX improvements to help users diagnose common configuration issues faster:

1. Artifact mismatch errors now include config context and actionable suggestions

Before: Generic messages like No artifacts matching filters found for revision "abc123" (tries: 3) — users had no idea what went wrong or how to fix it.

After: Error messages now include:

  • The user's .craft.yml artifact configuration rendered as YAML
  • List of available artifact/workflow names that were found (so users can spot the naming mismatch)
  • Actionable checklist of things to verify

Also upgrades the "no artifacts found" warning in printRevisionSummary to a hard error when .craft.yml explicitly defines artifact patterns — if you configured artifacts but none were found, that's a misconfiguration, not something to warn about.

Example improved error:

No artifacts matching your configured patterns were found for revision "abc123" after 3 attempts.

Found 1 workflow run(s), but none of their artifacts matched.
Available artifact names from matching runs: build-output, test-results

Check that:
  1. Your CI workflow is uploading artifacts with the expected names
  2. The artifact names in .craft.yml match what your CI actually produces

Your .craft.yml artifact configuration:
artifacts:
  Build & Test: [craft-binary, craft-docs]

2. Missing release branch error now suggests craft prepare and lists similar branches

Before: Raw git error error: pathspec 'release/1.2.3' did not match any file(s) known to git — completely opaque.

After: Clear error with:

  • Suggestion to run craft prepare
  • The configured release branch prefix (and whether it's the default)
  • Exact matches: existing release branches with the same prefix
  • Fuzzy matches (Levenshtein distance ≤ 3): branches with a similar prefix, catching typos like relaeserelease or releasesrelease

Example improved error:

Could not find the release branch "release/1.2.3".

Have you run `craft prepare` for version 1.2.3?

Release branch prefix: "release" (default)

Existing release branches:
  - origin/release/1.2.2
  - origin/release/1.2.1

Did you mean one of these? (similar branch prefix):
  - origin/releases/1.2.3

Changes

File Change
src/artifact_providers/github.ts Refactored getArtifactsFromWorkflowRuns to also return all seen artifact names; added formatArtifactConfigForError() helper; improved 3 error messages with config dumps and suggestions
src/commands/publish.ts Wrapped release branch checkout in try/catch with findReleaseBranches() for exact + fuzzy branch listing; upgraded printRevisionSummary zero-artifact warning to error when artifact config is set
src/utils/git.ts Added findReleaseBranches() — fetches remote, lists all branches, returns exact and fuzzy (edit distance ≤ 3) matches
package.json Added fastest-levenshtein dependency (zero-dep, 21kB) for fuzzy branch matching
src/artifact_providers/__tests__/github.test.ts Tests for formatArtifactConfigForError(), allNames return value, and new test helper
src/utils/__tests__/git.test.ts 10 tests for findReleaseBranches() covering exact, fuzzy, both, empty, HEAD filtering, limits, fetch failures

Test plan

  • 845 unit tests pass (all non-e2e)
  • Build succeeds
  • Lint passes (warnings only for _err catch params)
  • TypeScript type check passes

…elease branches

Two UX improvements to help users diagnose common configuration issues:

1. Artifact errors now show the user's .craft.yml config, list available
   artifact/workflow names, and give actionable checklist suggestions.
   Also upgrades the zero-artifact warning to a hard error when artifact
   patterns are configured.

2. Release branch checkout failures now explain that `craft prepare`
   needs to run first, show the configured branch prefix, and list both
   exact-match and fuzzy-match (Levenshtein distance <= 3) remote branches
   to help identify typos or naming mismatches.
Copy link
Contributor

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 3 potential issues.

Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.

- Scope checkout try/catch to release-branch path only, so --rev
  errors propagate unchanged; include original error in message
- Fix incorrect comment about git branch sorting (alphabetical, not
  chronological)
- Extract shared formatArtifactConfigForError() into utils/strings.ts
  to eliminate YAML formatting duplication between publish.ts and
  github.ts
Copy link

@sentrivana sentrivana left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🙏🏻

@BYK BYK merged commit 84cdfd9 into master Feb 12, 2026
16 checks passed
@BYK BYK deleted the fix/improve-error-messages branch February 12, 2026 11:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants