feat: emit pipeline/connector instance_not_found ConduitError codes

pkg/connector/codes.go

@@ -0,0 +1,29 @@
+// Copyright © 2026 Meroxa, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package connector
+
+import (
+	"github.com/conduitio/conduit/pkg/foundation/cerrors/conduiterr"
+	"google.golang.org/grpc/codes"
+)
+
+// Connector error codes. Every error carries one of these codes plus a
+// suggested fix, so an API, MCP, or UI consumer knows what happened without
+// parsing message text.
+var (
+	// CodeConnectorNotFound is raised when a referenced connector instance
+	// cannot be located.
+	CodeConnectorNotFound = conduiterr.Register("connector.instance_not_found", codes.NotFound)
+)

pkg/connector/service.go

@@ -16,12 +16,14 @@ package connector
 
 import (
 	"context"
+	"fmt"
 	"regexp"
 	"strings"
 	"time"
 
 	"github.com/conduitio/conduit-commons/database"
 	"github.com/conduitio/conduit/pkg/foundation/cerrors"
+	"github.com/conduitio/conduit/pkg/foundation/cerrors/conduiterr"
 	"github.com/conduitio/conduit/pkg/foundation/log"
 	"github.com/conduitio/conduit/pkg/foundation/metrics/measure"
 )
@@ -104,7 +106,15 @@ func (s *Service) List(context.Context) map[string]*Instance {
 func (s *Service) Get(_ context.Context, id string) (*Instance, error) {
 	ins, ok := s.connectors[id]
 	if !ok {
-		return nil, cerrors.Errorf("%w (ID: %s)", ErrInstanceNotFound, id)
+		// Invariant: errors.Is(err, ErrInstanceNotFound) still holds — the sentinel
+		// is wrapped, and the ConduitError adds the machine-actionable code.
+		err := conduiterr.Wrap(
+			CodeConnectorNotFound,
+			fmt.Sprintf("connector %q not found", id),
+			ErrInstanceNotFound,
+		)
+		err.Suggestion = "run `conduit connectors list` to see existing connectors"
+		return nil, err
 	}
 	return ins, nil
 }

pkg/connector/service_test.go

@@ -25,6 +25,7 @@ import (
 	"github.com/conduitio/conduit-commons/database/mock"
 	"github.com/conduitio/conduit-commons/opencdc"
 	"github.com/conduitio/conduit/pkg/foundation/cerrors"
+	"github.com/conduitio/conduit/pkg/foundation/cerrors/conduiterr"
 	"github.com/conduitio/conduit/pkg/foundation/log"
 	pmock "github.com/conduitio/conduit/pkg/plugin/connector/mock"
 	"github.com/google/uuid"
@@ -423,7 +424,11 @@ func TestService_GetInstanceNotFound(t *testing.T) {
 	// get connector that does not exist
 	got, err := service.Get(ctx, uuid.NewString())
 	is.True(err != nil)
-	is.True(cerrors.Is(err, ErrInstanceNotFound))
+	is.True(cerrors.Is(err, ErrInstanceNotFound)) // sentinel still in the chain
+	ce, ok := conduiterr.Get(err)
+	is.True(ok) // now also carries a machine-actionable ConduitError code
+	is.Equal(ce.Code.Reason(), CodeConnectorNotFound.Reason())
+	is.True(ce.Suggestion != "") // with a suggested fix
 	is.Equal(got, nil)
 }
 

pkg/pipeline/codes.go

@@ -0,0 +1,29 @@
+// Copyright © 2026 Meroxa, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package pipeline
+
+import (
+	"github.com/conduitio/conduit/pkg/foundation/cerrors/conduiterr"
+	"google.golang.org/grpc/codes"
+)
+
+// Pipeline error codes. Every error carries one of these codes plus a
+// suggested fix, so an API, MCP, or UI consumer knows what happened without
+// parsing message text.
+var (
+	// CodePipelineNotFound is raised when a referenced pipeline instance
+	// cannot be located.
+	CodePipelineNotFound = conduiterr.Register("pipeline.instance_not_found", codes.NotFound)
+)

pkg/pipeline/service.go

@@ -16,12 +16,14 @@ package pipeline
 
 import (
 	"context"
+	"fmt"
 	"regexp"
 	"strings"
 	"time"
 
 	"github.com/conduitio/conduit-commons/database"
 	"github.com/conduitio/conduit/pkg/foundation/cerrors"
+	"github.com/conduitio/conduit/pkg/foundation/cerrors/conduiterr"
 	"github.com/conduitio/conduit/pkg/foundation/log"
 	"github.com/conduitio/conduit/pkg/foundation/metrics/measure"
 )
@@ -104,7 +106,15 @@ func (s *Service) List(context.Context) map[string]*Instance {
 func (s *Service) Get(_ context.Context, id string) (*Instance, error) {
 	p, ok := s.instances[id]
 	if !ok {
-		return nil, cerrors.Errorf("%w (ID: %s)", ErrInstanceNotFound, id)
+		// Invariant: errors.Is(err, ErrInstanceNotFound) still holds — the sentinel
+		// is wrapped, and the ConduitError adds the machine-actionable code.
+		err := conduiterr.Wrap(
+			CodePipelineNotFound,
+			fmt.Sprintf("pipeline %q not found", id),
+			ErrInstanceNotFound,
+		)
+		err.Suggestion = "run `conduit pipelines list` to see existing pipelines"
+		return nil, err
 	}
 	return p, nil
 }

pkg/pipeline/service_test.go

@@ -23,6 +23,7 @@ import (
 	"github.com/conduitio/conduit-commons/database/inmemory"
 	"github.com/conduitio/conduit-commons/database/mock"
 	"github.com/conduitio/conduit/pkg/foundation/cerrors"
+	"github.com/conduitio/conduit/pkg/foundation/cerrors/conduiterr"
 	"github.com/conduitio/conduit/pkg/foundation/log"
 	"github.com/google/uuid"
 	"github.com/matryer/is"
@@ -312,7 +313,11 @@ func TestService_GetInstanceNotFound(t *testing.T) {
 	// get pipeline instance that does not exist
 	got, err := service.Get(ctx, uuid.NewString())
 	is.True(err != nil)
-	is.True(cerrors.Is(err, ErrInstanceNotFound))
+	is.True(cerrors.Is(err, ErrInstanceNotFound)) // sentinel still in the chain
+	ce, ok := conduiterr.Get(err)
+	is.True(ok) // now also carries a machine-actionable ConduitError code
+	is.Equal(ce.Code.Reason(), CodePipelineNotFound.Reason())
+	is.True(ce.Suggestion != "") // with a suggested fix
 	is.Equal(got, nil)
 }