Troubleshooting kongctl

This guide covers common issues and their solutions when using kongctl.

“Authentication required” or “unauthorized” errors

Symptom: Commands fail with authentication errors.

Solutions:

1. Verify you’re logged in:

   kongctl get me
   

   Copied!
2. Re-authenticate:

   kongctl logout
   kongctl login
   

   Copied!
3. If using a PAT, verify it’s set:

   echo $KONGCTL_DEFAULT_KONNECT_PAT | head -c 20
   

   Copied!

4. Check that the token hasn’t expired in Konnect.

5. Verify that region is configured as expected.

Browser login timeout

Symptom: Browser authorization doesn’t complete in time.

Solutions:

1. Complete authorization within the time limit (usually 15 minutes).

2. If timeout occurs, start over:

    kongctl login
   

   Copied!
3. Verify that your browser isn’t blocking the redirect.

Enable debug logging

You can enable debugging to see detailed operation logs:

export KONGCTL_DEBUG=1
export KONGCTL_LOG_LEVEL=debug
kongctl plan -f config/

Verify configuration

Verify that the configuration file is valid:

cat ~/.config/kongctl/config.yaml

Test API connectivity

Make a direct API call to test API connectivity:

kongctl api /v3/portals

Check version

Ensure you’re running the latest version:

kongctl version --full

Update kongctl if needed following the install instructions for your platform.

If you’re still experiencing issues, do the following:

1. Check GitHub issues for similar problems.

2. Review GitHub discussions.

3. Open a new issue with:
   • kongctl version (kongctl version --full)
   • Operating system
   • Command that failed
   • Full error message
   • Debug logs (with sensitive data redacted)
4. Contact Kong Support if you’re an enterprise customer.