feat: add structured IPC error types with miette diagnostics by jdx · Pull Request #181 · jdx/pitchfork

jdx · 2026-01-19T19:46:53Z

Summary

Add IpcError enum with structured error variants for IPC operations
Replace bail! calls with diagnostic error types that include helpful suggestions
Add context to serialization/deserialization errors (JSON vs MessagePack format)

Error Types Added

Error	When	Help Text
`ConnectionFailed`	Can't connect after retries	"ensure the supervisor is running with: pitchfork supervisor start"
`Timeout`	IPC request times out	"the supervisor may be unresponsive... Check status / View logs"
`ConnectionClosed`	Socket closes unexpectedly	"the supervisor may have crashed... Restart with: pitchfork supervisor start"
`UnexpectedResponse`	Wrong response type	"this may indicate a version mismatch between the CLI and supervisor"
`ReadFailed`/`SendFailed`	I/O errors	Shows error details
`InvalidMessage`	Corrupted message	"the message may have been corrupted"

Example Output

Error: pitchfork::ipc::connection_failed

  × failed to connect to supervisor after 5 attempts

  help: ensure the supervisor is running with: pitchfork supervisor start

Test plan

All existing tests pass
New unit tests for IPC error types
Lints pass

🤖 Generated with Claude Code

Note

Introduces structured, diagnosable IPC errors and propagates them through the IPC client, improving user-facing diagnostics and reliability.

Add IpcError variants (ConnectionFailed, Timeout, ConnectionClosed, ReadFailed, SendFailed, UnexpectedResponse, InvalidMessage) in src/error.rs with miette codes/help
Refactor src/ipc/client.rs to replace bail!/ensure with IpcError, add unexpected_response helper, map timeouts/IO errors/null-byte messages to specific variants, and surface connect retry failures with details
Enhance src/ipc/mod.rs serialization/deserialization to attach context for JSON/MessagePack and log a safe message preview
Add unit tests verifying IpcError display formatting

^{Written by Cursor Bugbot for commit 8f88aa3. This will update automatically on new commits. Configure here.}

Copilot

Pull request overview

This PR enhances IPC error handling by introducing a structured IpcError enum with diagnostic capabilities through the miette crate. The changes replace generic error messages with specific error variants that provide actionable help text to users when IPC communication fails.

Changes:

Added IpcError enum with 7 variants covering connection failures, timeouts, unexpected responses, and I/O errors
Replaced bail! macro calls with structured error types that include diagnostic codes and helpful suggestions
Enhanced serialization/deserialization error messages with format context (JSON vs MessagePack)

Reviewed changes

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

File	Description
src/error.rs	Defines the new `IpcError` enum with diagnostic attributes and includes unit tests for error display formatting
src/ipc/client.rs	Replaces `bail!` calls with `IpcError` variants throughout IPC client operations and adds a helper method for unexpected response errors
src/ipc/mod.rs	Adds format context to serialization/deserialization errors and improves trace logging for binary data

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

Copilot · 2026-01-19T19:47:32Z

src/ipc/mod.rs

+    let format = if *env::IPC_JSON {
+        "JSON"
+    } else {
+        "MessagePack"
+    };
    let msg = if *env::IPC_JSON {


The format string is determined twice using identical conditional logic. Consider storing the result of the first check and reusing it, or combine the format determination with the serialization call to reduce duplication.

Copilot · 2026-01-19T19:47:32Z

src/ipc/mod.rs

+    let format = if *env::IPC_JSON {
+        "JSON"
+    } else {
+        "MessagePack"
+    };
    let msg = if *env::IPC_JSON {


The format string is determined twice using identical conditional logic. Consider storing the result of the first check and reusing it, or combine the format determination with the deserialization call to reduce duplication.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

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

src/ipc/client.rs

Introduce IpcError enum for better error reporting in IPC operations: - ConnectionFailed: suggests running `pitchfork supervisor start` - Timeout: indicates supervisor may be unresponsive - ConnectionClosed: suggests supervisor may have crashed - ReadFailed/SendFailed: with error details - UnexpectedResponse: shows expected vs actual response - InvalidMessage: for corrupted messages Also improves serialization error context with format info (JSON/MessagePack). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add details field to IpcError::ConnectionFailed to preserve the underlying error (e.g., 'connection refused', 'no such file') - Pass error details when connection attempts are exhausted - Remove duplicate format string logic in serialize/deserialize by inlining the format name directly in each branch Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

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

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

Copilot · 2026-01-19T22:24:23Z

src/ipc/client.rs

+                        return Err(IpcError::ConnectionFailed {
+                            attempts: CONNECT_ATTEMPTS,
+                            details: Some(format!(
+                                "{err}\nensure the supervisor is running with: pitchfork supervisor start"


The help text 'ensure the supervisor is running with: pitchfork supervisor start' is duplicated in the details field here (line 70-71) and in the fallback case (lines 81-82). Consider extracting this message to a constant to maintain consistency.

Copilot · 2026-01-19T22:24:23Z

src/ipc/mod.rs

+    let preview = std::str::from_utf8(&bytes).unwrap_or("<binary>");
+    trace!("msg: {:?}", preview);


The variable name 'preview' suggests this is a limited view of the data, but the code attempts to convert the entire bytes buffer to UTF-8. Consider renaming to 'message_text' or 'decoded_message' to better reflect that it represents the full decoded content or a fallback label.

Suggested change

let preview = std::str::from_utf8(&bytes).unwrap_or("<binary>");

trace!("msg: {:?}", preview);

let decoded_message = std::str::from_utf8(&bytes).unwrap_or("<binary>");

trace!("msg: {:?}", decoded_message);

## 🤖 New release * `pitchfork-cli`: 1.1.0 -> 1.2.0 <details><summary>Changelog</summary> <blockquote> ## [1.2.0](v1.1.0...v1.2.0) - 2026-01-19 ### Added - enhance miette error diagnostics with source highlighting and URLs ([#183](#183)) - add structured IPC error types with miette diagnostics ([#181](#181)) - add structured config error types with file path context ([#182](#182)) - add config editor to TUI for creating and editing daemons ([#171](#171)) - add custom diagnostic error types with miette ([#180](#180)) ### Other - improve miette error handling adoption ([#177](#177)) - modularize supervisor.rs into focused submodules ([#175](#175)) </blockquote> </details> --- This PR was generated with [release-plz](https://github.com/release-plz/release-plz/).  --- > [!NOTE] > **Release 1.2.0** > > - Bump version to `1.2.0` in `Cargo.toml`, `Cargo.lock`, `docs/cli/commands.json`, `docs/cli/index.md`, and `pitchfork.usage.kdl` > - Regenerate CLI docs/usage specs to reflect the new version > - Update `CHANGELOG.md` with highlights: enhanced `miette` diagnostics (source highlighting, URLs), structured IPC/config error types, custom diagnostic errors, TUI config editor; plus adoption improvements and supervisor modularization > > Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 32b3259. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).  --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Copilot AI review requested due to automatic review settings January 19, 2026 19:46

Copilot AI reviewed Jan 19, 2026

View reviewed changes

cursor bot reviewed Jan 19, 2026

View reviewed changes

src/ipc/client.rs Show resolved Hide resolved

jdx and others added 2 commits January 19, 2026 16:23

jdx force-pushed the feat/miette-ipc-errors branch from 3f94fc4 to 8f88aa3 Compare January 19, 2026 22:23

Copilot AI review requested due to automatic review settings January 19, 2026 22:23

Copilot AI reviewed Jan 19, 2026

View reviewed changes

jdx merged commit 667d5c1 into main Jan 19, 2026
4 checks passed

jdx deleted the feat/miette-ipc-errors branch January 19, 2026 22:37

jdx mentioned this pull request Jan 19, 2026

chore: release v1.2.0 #178

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add structured IPC error types with miette diagnostics#181

feat: add structured IPC error types with miette diagnostics#181
jdx merged 2 commits intomainfrom
feat/miette-ipc-errors

jdx commented Jan 19, 2026 •

edited by cursor bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

cursor bot left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Copilot AI Jan 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		let preview = std::str::from_utf8(&bytes).unwrap_or("<binary>");
		trace!("msg: {:?}", preview);

Conversation

jdx commented Jan 19, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Error Types Added

Example Output

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jdx commented Jan 19, 2026 •

edited by cursor bot

Loading