Troubleshoot Configuration
Fix common issues you may encounter when configuring the SDK, like a missing API key or commands that use the wrong environment.
Add --verbose (or -v) before the command name to see the SDK's INFO and DEBUG logs. It's a global option, so it must come before the command, not after.
"API key is required"
Run haystack-enterprise login, set the environment variable, or pass --api-key. For help, see Set Up Configuration.
If you logged in and you're still seeing this error, a local .env in the directory you're running from may be shadowing the global one. The local file takes precedence.
Commands Use the Wrong Environment
API_URL resolved to something unexpected. The same precedence applies: an API_URL in your shell takes precedence over a local .env, which takes precedence over the global one. A trailing /api/v1 is stripped automatically, so pasting a full endpoint URL is safe.
haystack-enterprise: command not found
The scripts directory of the environment you installed into isn't on your PATH. After uv tool install, add the uv tools directory (often ~/.local/bin) to your PATH, or run uv tool update-shell. python -m haystack_enterprise_sdk.cli works only if that Python environment has the SDK installed. For help, see Install the SDK and Troubleshoot Installation.
CERTIFICATE_VERIFY_FAILED Behind a Corporate Proxy
A TLS-inspecting corporate proxy re-signs HTTPS traffic with its own root certificate. That certificate is usually installed in your operating system's trust store (for example, the Windows certificate store), which is why your browser accepts it. If the SDK checked certificates against a bundled list instead, login and other commands would fail with CERTIFICATE_VERIFY_FAILED.
The haystack-enterprise CLI checks certificates against the operating system trust store, so a proxy certificate installed in Windows or macOS is trusted without extra setup. If the error persists, make sure the proxy's root certificate is installed in the operating system trust store, and ask your IT team if you're not sure.
The SDK used as a Python library doesn't change how Python verifies certificates. If you call the SDK from your own code behind such a proxy and see this error, call truststore.inject_into_ssl() once at startup, before you create a client. The truststore package is installed with the SDK.
The Browser Login Page Reports an Invalid Link or Can't Create a Key
When haystack-enterprise login --no-device opens the Authorize page, the page may not complete the login:
- The link is invalid. The link is missing or has a malformed port or state value. This happens when you open an old or edited link. Run
haystack-enterprise login --no-deviceagain and use the new link that the CLI opens. - The page can't create an API key. You may not have permission to create API keys in the selected workspace, or you have no role in it. Select a different workspace, or ask a workspace admin to give you a role that can create API keys.
- The terminal doesn't receive the key. The page sends the key to the CLI on your own machine, so the browser and the CLI must run on the same machine. If you work over SSH or in a container, run
haystack-enterprise loginwithout--no-deviceto log in with a code instead, or use--api-keyand--workspace-name. For details, see Set Up Configuration.
Related Information
Was this page helpful?