Troubleshooting

This page covers the most common problems encountered when using the OptixLog SDK and CLI. Each section describes the symptom, the cause, and the fix.

Authentication failures

Symptom: The CLI prints error: ... and exits 1 with a message about an API key or authentication. In Python code, AuthenticationError is raised.

Causes:

• The API key is missing — neither OPTIXLOG_API_KEY, --api-key, nor a saved credential in ~/.optixlog/credentials.toml was found.
• The API key is invalid or has been revoked.
• The key has the wrong format (must start with sk-opt-).
• The wrong profile is selected (--profile <name> points to an empty or missing profile entry).

optixlog login --api-key sk-opt-yourkey
# or
export OPTIXLOG_API_KEY=sk-opt-yourkey

In Python code, catch AuthenticationError:

from optixlog import AuthenticationError, SDKClient

try:
    client = SDKClient(base_url="https://optixlog.leidos.com", api_key="sk-opt-...")
    mgmt = Management(client)
    # ...
except AuthenticationError as exc:
    print(f"Authentication failed: {exc}")

"no accessible projects for this key"

Symptom: optixlog init exits 1 with error: no accessible projects for this key.

Causes:

• The API key is a service key scoped to specific projects and those projects have been removed or the key's scope has changed.
• The key belongs to a different organization than the one you expect.
• A fixture is being used that has an empty projects array.

optixlog whoami
optixlog whoami --validate   # re-check against the server

Stale generated bindings (generate --check failing)

Symptom: optixlog generate --check exits 1 with:

error: optixlog_gen.py is out of date; re-run `optixlog generate`.

Cause: The schema on the server (or in your fixture) has changed since the last time you ran optixlog generate. The --check flag compares the current output file byte-for-byte against what would be generated now and exits 1 if they differ. This is the expected behavior in CI — it enforces that committed bindings are always in sync with the schema.

optixlog generate
git add optixlog_gen.py
git commit -m "chore: regenerate optixlog bindings"

"no optixlog.toml found"

Symptom: optixlog generate exits 1 with:

error: no optixlog.toml found; run `optixlog init` first.

Cause: The CLI walks up from the current working directory looking for optixlog.toml and did not find one. Either optixlog init has not been run, or you are running the command from outside your project tree.

cd /path/to/your/project
optixlog init

optixlog generate --config-path /path/to/optixlog.toml

Fixture / offline issues

Symptom: Commands fail with network errors, or you want to work without a live server connection. You have a fixture JSON file but are unsure how to use it.

Cause: Without --fixture, all CLI commands and SDK calls attempt live network requests to https://optixlog.leidos.com. In environments without network access (local tests, CI without secrets, demo environments), you need to point the CLI at a local fixture.

# Offline login (saves a credential using the fixture's identity)
optixlog login --fixture tests/fixtures/schema.sample.json \
               --api-key sk-opt-test \
               --base-url http://localhost

# Offline init
optixlog init --fixture tests/fixtures/schema.sample.json --all

# Offline generate
optixlog generate --fixture tests/fixtures/schema.sample.json

export OPTIXLOG_FIXTURE=tests/fixtures/schema.sample.json
optixlog init --all
optixlog generate

See Offline Fixture Workflow for the full walkthrough and guidance on writing your own fixtures.

Static type-check errors when passing a wrong node type to a project

Symptom: pyright reports reportArgumentType or mypy reports [call-overload] when you pass a node type to project().ingest(). For example:

client.project(Projects.GRATING_COUPLER_LAB).ingest(
    data=LayoutNode(gds_path="x.gds"),  # type error here
    prompt="...",
)

Cause: This is the intended behavior — it is not a bug. The generated OptixClient.project() overloads are typed so that each project's ingest only accepts node types that belong to that project's schema. LayoutNode is defined only in proj_modulator_22b1, not in proj_grating_7f3a. Passing it to the wrong project is a static type error.

# LayoutNode belongs to MODULATOR_PROGRAM, not GRATING_COUPLER_LAB
client.project(Projects.MODULATOR_PROGRAM).ingest(
    data=LayoutNode(gds_path="x.gds"),
    prompt="Layout for the modulator.",
)

For a full explanation of how the typing mechanism works, see Type Safety Guarantees and Generated Module Anatomy.

NotFoundError vs get_or_none

Symptom: Your code raises NotFoundError when looking up a workflow node, team, or other resource by id, and you want to handle the "not found" case gracefully rather than catching an exception.

Cause: The get(id) methods on all management collections raise NotFoundError when the resource does not exist. This is by design — it makes missing resources an explicit signal rather than a silent None return.

# Raises NotFoundError if the node does not exist
node = mgmt_project.workflow_nodes.get("node_id_that_may_not_exist")

# Returns None if the node does not exist
node = mgmt_project.workflow_nodes.get_or_none("node_id_that_may_not_exist")
if node is None:
    print("Node not found — skipping.")
    return

Credentials file permissions

Symptom: optixlog login fails with a CredentialsError about file permissions, or Python raises a permission-related OSError when loading credentials.

Cause: ~/.optixlog/credentials.toml must be readable and writable only by the owning user (mode 0600) and ~/.optixlog/ must have mode 0700. If the file was created with looser permissions (e.g. by a script running as root, or after a umask change), the SDK will refuse to load it.

chmod 0700 ~/.optixlog
chmod 0600 ~/.optixlog/credentials.toml

sudo chown -R "$USER" ~/.optixlog
chmod 0700 ~/.optixlog
chmod 0600 ~/.optixlog/credentials.toml

ls -la ~/.optixlog/

export OPTIXLOG_CONFIG_HOME=/path/to/secure/dir
optixlog login