Skip to content

Errors and troubleshooting

The SDK turns transport and API failures into skyportalai exceptions. The CLI reports the same errors as messages and exit codes.

Exception hierarchy

SkyportalError
├── APIConnectionError
├── WaitTimeoutError
└── APIStatusError
    ├── AuthenticationError
    └── APIError
Exception Raised when
SkyportalError The client can't be configured: no API key, an invalid or insecure base_url, or a leftover SKYPORTAL_BASE_URL
APIConnectionError SkyPortal can't be reached, or the request times out
WaitTimeoutError wait() runs out of time while the chat is still busy
AuthenticationError The API key is missing or rejected
APIError Any other error status, or a response that isn't valid JSON. status_code and body hold the details 
from skyportalai import (
    APIConnectionError,
    APIError,
    AuthenticationError,
    Skyportal,
    WaitTimeoutError,
)

try:
    with Skyportal() as client:
        chat = client.chat.create_chat("Check service health", server_id=42)
        chat.wait(timeout=120)
except AuthenticationError:
    print("The API key was missing or rejected")
except APIConnectionError:
    print("SkyPortal could not be reached")
except WaitTimeoutError:
    print("The workflow is still running")
except APIError as error:
    print(error.status_code, error.body)

Retries

  • Only GET requests are retried.
  • Network failures, timeouts and HTTP 5xx responses are retried.
  • The default is 2 retries after the first attempt.
  • The wait between attempts starts at 0.5 seconds and doubles each time.
  • Requests that change something are never retried automatically.

CLI exit codes

Code Meaning
0 The command completed
1 Configuration, authentication, connection, API or workflow error
2 Waiting for approval, or a usage error

If a script gets exit code 2 with awaiting_approval, ask a person to review the action instead of retrying.

Common problems

"SKYPORTAL_BASE_URL was removed in 0.3.0 and is ignored; set SKYPORTALAI_BASE_URL instead." An old variable is still set. The CLI refuses to fall back to the default host, because that host would then receive your credential. Set SKYPORTALAI_BASE_URL to the API target you want before you unset SKYPORTAL_BASE_URL. If you only unset it, the CLI can end up on the default host after all. See Upgrading to 0.3.

A warning that another SKYPORTAL_* variable "was removed in 0.3.0 and is ignored" Rename it to SKYPORTALAI_*. Until then its value is not used.

"No API key provided. Pass api_key=... or set the SKYPORTALAI_API_KEY environment variable." The SDK found no key. Old SKYPORTAL_API_KEY values are ignored since 0.3.0.

"Not connected. Run 'skyportalai login' first." The interactive terminal has no saved credential. Run skyportalai login, or /login inside the terminal.

"Stored credentials belong to another Skyportal deployment ..." Your saved credential was created for a different API target than the one selected now. Run skyportalai logout and sign in again, or select the original target. skyportalai config show shows the conflict.

"Agent deployment tokens (agt_) only upload observability data ..." You pasted an agent token into the CLI. Use an API key (sk_) instead.

"No namespace selected for ..." A Kubernetes cluster is selected but has no namespace. Pick one with /namespace NAME or /namespace all.

403 "MFA enrollment is required before this credential can be used." Your organization requires two-factor authentication and you haven't set it up yet. Every API credential is refused until you do. See Security.

Checklist

  1. skyportalai config show reports the API target, the credential source and any conflict.
  2. Global options such as --json and --base-url go before the subcommand.
  3. Timeouts must be greater than zero.
  4. Chat IDs and approval IDs must be current. Read them from chat status.
  5. In automation, use skyportalai --json and check the exit code.