> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Port execution agent troubleshooting

Answers to common questions and issues when running the Port execution agent.

Why does the agent fail with a 401 Unauthorized error on startup?​

Answer (click to expand)

The agent pod logs show:

ERROR:port_client:Failed to get Port API access token - status: 401,
response: {"ok":false,"error":"invalid_credentials",
"message":"Invalid credentials supplied to the generate token API"}

The agent fails to start and cannot get Kafka credentials.

Cause: The clientId or clientSecret values in the Helm chart are incorrect or empty.

Fix:

  1. Verify the values in your Helm install command:
helm install my-port-agent port-labs/port-agent \
  --set port.clientId="YOUR_CLIENT_ID" \
  --set port.clientSecret="YOUR_CLIENT_SECRET" \
  --set port.baseUrl="https://api.getport.io"   # or api.us.getport.io for US region
  1. Verify the baseUrl matches your Port region. US-hosted orgs must use https://api.us.getport.io, not https://api.getport.io.
  2. Regenerate your client credentials in Port → Settings → Credentials if unsure whether they are valid.
US and EU base URLs

The baseUrl is the most common mistake for US-region customers. Using the EU URL silently returns 401 for US credentials.

Why is the agent failing with Kafka consumer group authorization errors?​

Answer (click to expand)

Agent logs show:

KafkaError{code=GROUP_AUTHORIZATION_FAILED,val=30,
str="FindCoordinator response error: Group authorization failed."}

Cause: The Kafka consumer group ID used by the agent is not authorized for the organization's Kafka topic. This happens when Kafka credentials have not been provisioned for the organization, or when the agent is configured with the wrong organization ID.

Fix:

  1. Verify your Port organization has Kafka credentials provisioned. Contact Port support to enable Kafka for your org if it was recently created.
  2. Verify the port.clientId and port.clientSecret belong to the correct organization because credentials are org-specific.

Why does the agent time out during action execution?​

Answer (click to expand)

Agent logs show:

ERROR:consumers.kafka_consumer:Failed process message from topic
org_xxxxx.runs, partition 0, offset N:
HTTPSConnectionPool(host='your-backend.example.com', port=443):
Read timed out. (read timeout=30.0)

The action run stays in In Progress indefinitely in Port.

Cause: The backend service (GitHub Actions, GitLab pipeline, webhook endpoint) did not respond within the agent's 30-second read timeout.

Fix:

  1. Your backend must respond with an HTTP 2xx within 30 seconds of receiving the request. Long-running operations should respond immediately with 200, then report completion asynchronously using Port's run update API.
  2. Increase the timeout if you control the agent configuration:
--set agent.httpTimeout=60
  1. Check that your backend host is reachable from the agent pod's network. Corporate VPNs and ACLs frequently block outbound connections from Kubernetes namespaces.

Why does the agent fail with TLS certificate errors on startup?​

Answer (click to expand)

The agent fails with SSL or TLS errors when connecting to api.getport.io or to your backend service.

Common causes and fixes:

  • Corporate CA not trusted: Mount your corporate CA bundle into the pod and set SSL_CA_BUNDLE=/path/to/ca-bundle.crt in the environment.
  • Self-signed cert on backend: Set SSL_VERIFY=false in the agent environment for non-production environments only. Never disable SSL verification in production.
  • EKS with custom networking: Ensure the pod's service account has outbound HTTPS access (port 443) to api.getport.io and api.us.getport.io.