Troubleshooting

This page helps you isolate and fix a problem in a running deployment, working from infrastructure up to the data plane. Use the diagnostic workflow to find the layer at fault, confirm the health signals, then jump to the issue matrix for the specific symptom you are seeing.

Structured Diagnostic Workflow

If you encounter an issue, follow this checklist in order to isolate the root cause:

Two of the decision nodes above need a concrete signal to answer:

Adapter Status in Portal? Read the adapter's status from the Portal's Adapters list (or its per-adapter status panel). The equivalent metric signals are adapter_lifecycle_state and adapter_operational_status; the ERROR label corresponds to adapter_operational_status{status="unhealthy"}.
Data Flowing? An adapter can report ACTIVE yet pass no traffic, so confirm messages are actually moving:
- Check that no route is halted. adapter_pipeline_open_circuit_breakers must be 0. A value greater than 0 means a route's circuit breaker is open and messages have stopped flowing on that route even though the source connector may still show as connected.
- Check that the adapter reports adapter_operational_status{status="healthy"} rather than degraded, since a partial connector failure can leave some routes idle.
- Watch the source and target throughput counters the connector plugins emit (per-message metrics are plugin-specific; see the plugin's own reference under Official Plugins). Flat counters while upstream has traffic confirms the pipeline is stalled.
If all three hold and messages are still not arriving, the source has nothing new to send or a pipeline condition is dropping everything (see the issue matrix below).

1. The "Golden Signals" of the Platform

Before diving deep, verify these health signals:

Orchestrator Liveness: kubectl exec deploy/conncentric-orchestrator -n conncentric -- curl -sf http://localhost:8080/actuator/health should report status UP.
Database Connectivity: Check Orchestrator logs for successful database connection messages.
Adapter Heartbeats: The Portal's Adapters list should show adapters as Running with no entries in ERROR state.

Diagnostic tools may not be present in the image

The kubectl exec ... -- <tool> commands on this page assume the tool (curl, nc, nslookup, psql) is present inside the container. Slim application images often omit them, and the command then returns command not found. When that happens, attach an ephemeral debug container that carries the tools rather than installing anything into the running pod:

# Attach a throwaway container with networking tools to a running pod,
# sharing that pod's network namespace:
kubectl debug -it <pod-name> -n conncentric \
  --image=nicolaka/netshoot --target=<container-name>

# Or run a short-lived standalone tools pod in the namespace:
kubectl run netshoot --rm -it -n conncentric --image=nicolaka/netshoot -- /bin/bash

A networking image such as netshoot provides curl, nc, nslookup, and dig. For the database client (psql), pick a tools image that ships it, for example a Postgres client image. From the debug container, run the same host and port arguments shown in the commands below. Treat the inline kubectl exec commands as the shortcut for when the tool is already present in the image.

Where to Look First

Check What's Running

kubectl get pods -n conncentric

All three pods (Orchestrator, Adapter, and Portal) should show Running. If one is in CrashLoopBackOff or Error, check its logs:

kubectl logs <pod-name> -n conncentric --tail=200

Check Adapter Status

Open the Portal and navigate to the Adapters list. It shows every adapter and its Operational Status. Scan for anything not Running: an adapter stuck in Provisioning for more than a few seconds means something is preventing a pod from picking it up, and an adapter in Error needs its event log read.

Portal labels vs. metric state values

The Portal shows each adapter's status as a single Operational Status label (Running, Provisioning, Standby, Error, Inactive, and so on), whereas the metrics expose two separate dimensions: an adapter_lifecycle_state and an adapter_operational_status. The Portal derives its label from both:

Portal label	Metric state
`Running`	`lifecycle_state` = `active` with `operational_status` = `healthy`
`Degraded`	`lifecycle_state` = `active` with `operational_status` = `degraded`
`Error`	`lifecycle_state` = `active` with `operational_status` = `unhealthy`
`Provisioning` / `Releasing`	`lifecycle_state` = `provisioning` / `releasing` (the platform is placing or removing the adapter)
`Standby`	`lifecycle_state` = `standby` (awaiting the primary lease)
`Paused`	`lifecycle_state` = `paused`
`Ports Exhausted`	`lifecycle_state` = `port_exhaustion`
`Inactive`	`lifecycle_state` = `inactive`

The Portal is authoritative for the exact label an adapter shows: it combines both dimensions into the single label on the Adapters list. See Metrics & Monitoring for the full set of lifecycle_state and operational_status values and their meanings.

Common issues

Symptom	Likely cause	Action
Adapter stuck in `Provisioning` for more than a few seconds	No pod has picked up the session: all adapter pods are down, the adapter is disabled, or the pool is saturated	Confirm at least one adapter pod is `Running` (`kubectl get pods -n conncentric`) and the adapter is enabled in the Portal. If the pool is saturated, raise `adapter.replicaCount`.
Connection established but the session never activates	Wrong session credentials or identifiers, a protocol version mismatch, or TLS misconfigured at the boundary	Recheck the connector settings in the Portal. Test reachability from the pod: `kubectl exec -it <adapter-pod> -n conncentric -- nc -zv <host> <port>`. Read the event log for the counterparty's rejection reason.
`Connection refused` in the Orchestrator logs at startup	Wrong `database.host`, the database is unreachable from the cluster, or wrong credentials	Confirm DNS: `kubectl exec -it <orchestrator-pod> -n conncentric -- nslookup <db-host>`. Test the connection: `kubectl exec -it <orchestrator-pod> -n conncentric -- psql -h <db-host> -U <username> -d <database>`.
Portal loads but shows "Unable to reach the server"	The Orchestrator pod is down, or the Ingress is not routing `/api` to the Orchestrator	`kubectl get pods -l app.kubernetes.io/component=orchestrator -n conncentric`; `kubectl describe ingress -n conncentric`.
Adapter is `ACTIVE` but no messages are flowing	The source has no new messages, the source endpoint is misconfigured or unreachable, a route's circuit breaker is open (`adapter_pipeline_open_circuit_breakers > 0`), or a pipeline condition is dropping everything	Confirm the source has messages via its own admin interface. Test reachability: `kubectl exec -it <adapter-pod> -n conncentric -- nc -zv <host> <port>`. Review the pipeline conditions in the Portal.
`adapter_pipeline_open_circuit_breakers > 0` (a route is halted)	Downstream target unreachable; the route's circuit breaker tripped	Confirm the downstream is healthy, then restart the adapter to clear the halt. See the circuit breaker runbook.

For protocol-specific rejections and tuning, see the relevant guide under Official Plugins.

Getting Help

When contacting support, include:

Pod description: kubectl describe pod <pod-name> -n conncentric
Full logs with timestamps: kubectl logs <pod-name> -n conncentric --timestamps > pod.log
Adapter summary from the Portal's Adapters list (screenshot or export)
Your Helm values (with passwords removed)
Kubernetes version: kubectl version

Structured Diagnostic Workflow​

1. The "Golden Signals" of the Platform​

Where to Look First​

Check What's Running​

Check Adapter Status​

Common issues​

Getting Help​

See also​