feat: add helpful hints when connection create/upsert fails with invalid resource IDs by leggetter · Pull Request #205 · hookdeck/hookdeck-cli

leggetter · 2026-02-05T03:05:22Z

Summary

Fixes #204

When using --source-id or --destination-id flags and the API returns a 404 Not Found error, the CLI now displays helpful hints about expected ID formats to help users identify when they've provided the wrong type of ID.

Changes

Added enhanceConnectionError() shared method in connection_create.go that detects 404/Not Found errors
When --source-id or --destination-id is provided and an error occurs, displays hints about ID formats
Both connection create and connection upsert commands share the same logic
Added 6 acceptance tests covering error scenarios and positive case

Example Output

For the bug report scenario where a connection ID (web_) was mistakenly used instead of a source ID (src_):

$ hookdeck connection create --name "octolens-mentions-raw" \
    --source-id "web_y0A7nz0tRxZy" \
    --destination-type HTTP \
    --destination-name "modal-octolens-mentions-raw" \
    --destination-url "https://example.com"

failed to create connection: error: Not Found

Hints:
  - --source-id 'web_y0A7nz0tRxZy' was provided. Source IDs typically start with 'src_'.

Please verify the resource IDs exist and are the correct type.

Test Plan

Added acceptance tests for non-existent source ID
Added acceptance tests for non-existent destination ID
Added acceptance test reproducing issue connection create command failing #204 (wrong ID type)
Added acceptance tests for upsert command
Added positive test for valid existing source ID
All existing acceptance tests pass

Made with Cursor

…lid resource IDs When using --source-id or --destination-id flags and the API returns a 404 Not Found error, the CLI now displays helpful hints about expected ID formats: - Source IDs typically start with 'src_' - Destination IDs typically start with 'des_' This helps users identify when they've provided the wrong type of ID (e.g., using a connection ID 'web_xxx' instead of a source ID 'src_xxx'). Fixes #204 Example output for the bug report scenario: ``` $ hookdeck connection create --name "my-conn" --source-id "web_y0A7nz0tRxZy" \ --destination-type HTTP --destination-name "my-dest" \ --destination-url "https://example.com" failed to create connection: error: Not Found Hints: - --source-id 'web_y0A7nz0tRxZy' was provided. Source IDs typically start with 'src_'. Please verify the resource IDs exist and are the correct type. ``` Co-authored-by: Cursor <cursoragent@cursor.com>

Copilot

Pull request overview

This PR adds helpful error hints when connection create/upsert commands fail with 404 Not Found errors, helping users identify when they've provided incorrect resource ID types (e.g., using a connection ID instead of a source ID).

Changes:

Added error enhancement logic that detects 404 errors and displays hints about expected ID format for --source-id and --destination-id flags
Shared enhanceConnectionError() method between connection create and connection upsert commands
Added 6 acceptance tests covering error scenarios with non-existent IDs, wrong ID types, and a positive test case

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
pkg/cmd/connection_create.go	Added `enhanceCreateError()` and `enhanceConnectionError()` methods to detect 404 errors and provide helpful hints about resource ID formats
pkg/cmd/connection_upsert.go	Updated error handling to use the shared `enhanceConnectionError()` method from the embedded connectionCreateCmd
test/acceptance/connection_error_hints_test.go	Added comprehensive acceptance tests covering error scenarios with non-existent source/destination IDs, wrong ID types, and valid existing source ID usage

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-05T03:10:07Z

pkg/cmd/connection_create.go

+			hints = append(hints, fmt.Sprintf("  - --source-id '%s' was provided. Source IDs typically start with 'src_'.", cc.sourceID))
+		}
+		if cc.destinationID != "" {
+			hints = append(hints, fmt.Sprintf("  - --destination-id '%s' was provided. Destination IDs typically start with 'des_'.", cc.destinationID))


The destination ID prefix in the hint message is incorrect. According to the documentation (REFERENCE.md:906) and unit tests (pkg/hookdeck/connections_test.go:270), destination IDs use the prefix 'dest_', not 'des_'. The hint message should say "Destination IDs typically start with 'dest_'." to be consistent with the actual API.

Suggested change

hints = append(hints, fmt.Sprintf(" - --destination-id '%s' was provided. Destination IDs typically start with 'des_'.", cc.destinationID))

hints = append(hints, fmt.Sprintf(" - --destination-id '%s' was provided. Destination IDs typically start with 'dest_'.", cc.destinationID))

@copilot you are incorrect. destination IDs start with des_. Where did you get your information from?

Copilot · 2026-02-05T03:10:08Z