Troubleshooting

Find the next step.

Start with the message you see. Share an error without its secret key if you need help.

I have a key. Where do I paste it?

In the terminal, after running uv run optionspace login in your research folder. Wait for OptionSpace API key (input hidden):, paste (Ctrl+V or right-click in Windows PowerShell, Command+V on macOS, Ctrl+Shift+V in most Linux terminals), then press Enter. No characters or dots appear while pasting. Do not paste into this website, your code or an AI conversation.

Nothing appears when I paste

That is expected at the hidden key prompt. Press Enter once. If you are unsure what you pasted, press Ctrl+C, run the login command again, and paste once. The success message begins “stored in the keyring store.”

“That does not look like an OptionSpace API key”

Copy the one-time secret from the account page. It begins with sk_os_. The public key identifier shown in the key list begins with osk_ and cannot authenticate. Do not add quotation marks around the secret at the prompt.

If you no longer have the secret, create a replacement key through your account; the key list does not reveal an existing secret again.

“The key was rejected” / “nothing stored”

Check that you copied the complete secret and that the key is still active. A revoked key cannot be restored by logging in again. Use an active replacement, then rerun login. If verification cannot reach the server, retry when connectivity is restored; the failed attempt does not save the key.

“Command not found” or “No module named optionspace”

uv is not found right after installing it: close the terminal and open a new one, so it picks up the new command.

Otherwise, return to the folder where you installed the package and check it there:

cd optionspace-research
uv run optionspace --version

The version should be 0.9.0 or later. To update, run uv add --upgrade "optionspace[charts,mcp]" in that folder. uv run only finds the package from inside the folder you installed it in. See Getting started.

If you installed with pip instead, use that environment's Python: .venv/bin/python -m optionspace --version (Windows: .venv\Scripts\python -m optionspace --version).

For notebooks, select the same Python environment as the kernel. Installing into one environment does not make a package available to every notebook kernel.

Keychain, profiles and conflicting credentials

Where the key is kept

In your system's credential store: Credential Manager on Windows, Keychain on macOS, the Secret Service (GNOME Keyring or KWallet) on Linux. macOS may ask whether Python may read it: allow it. Use the same research folder for login, Python and MCP; another Python can trigger another prompt.

On a Linux server with no desktop there is no credential store. Either set OPTIONSPACE_API_KEY in the environment, or opt into an owner-only file with uv run optionspace login --store file (it is plaintext; use it only on a machine you control).

I logged in, but the wrong account is being used

Run uv run optionspace whoami and inspect source, profile and server. A key supplied directly in code takes priority over an environment variable; OPTIONSPACE_API_KEY takes priority over a stored profile. An old environment key can therefore hide a newly saved key.

If you intended to use the saved credential, remove the old environment override in that terminal, then check again. macOS or Linux:

unset OPTIONSPACE_API_KEY
uv run optionspace whoami

Windows (PowerShell):

Remove-Item Env:OPTIONSPACE_API_KEY
uv run optionspace whoami

I need separate accounts or environments

Use named profiles:

uv run optionspace login --profile research
uv run optionspace whoami --profile research

import optionspace as osp
client = osp.Client(profile="research")

For MCP, run uv run optionspace mcp --print-config --profile research; the setup it prints carries the profile. A stored credential is bound to the server used during login. Do not change its server by editing saved metadata.

I rotated or revoked a key

After rotation, log in with the new secret. uv run optionspace logout forgets the local copy; it does not revoke the server-side key. Revoke a key on the account page to disable it everywhere.

The key works, but a query is refused

Check uv run optionspace whoami, then inspect the error. Your key may allow a different date range, snapshot frequency or set of fields. A successful login confirms authentication, not unlimited data access.

The April 2025 examples require that period to be included in your grant. A free sample may use a different window. Choose an allowed session and use symbol/snapshot/expiry discovery before querying.

For 429, read the returned limit reason and retry guidance. Repeatedly resubmitting a request cannot remove a daily credit allowance or a concurrency limit. A 412 means a research call would cost more than the max_credits you set; it was not run. See credits.

MCP does not connect

1. Run uv run optionspace whoami in your research folder.
2. Run uv run optionspace mcp --print-config there and compare its output with your AI client's configuration: the command must be that absolute path.
3. Check the profile name, if one is specified.
4. Restart the AI client or reconnect the MCP server after changing configuration.
5. In Claude Code, check /mcp and the tool-connection message.

If you ran optionspace mcp directly and see a blank terminal, stop it with Ctrl+C. The AI client should launch that protocol process; ask questions inside the AI client instead.

A chart does not appear, or image export fails

The Python chart functions return figures; they do not automatically open a window. Save interactive HTML and open it in a browser:

fig.write_html("chart.html", include_plotlyjs=True)

MCP research tools return the generated file path. Open that path on the same machine. A remote client cannot necessarily open a local file from your computer.

Interactive HTML does not require a separate Chrome process. PNG/SVG/PDF export uses image-rendering dependencies and a compatible Chrome installation; video export also needs FFmpeg. If an exporter quits unexpectedly, use interactive HTML for now and send the exact error and your package/Python versions to us. Do not repeatedly relaunch a crashing exporter.

Get help

Email [email protected] with: what you did (the command or code, and the symbol, date and other inputs); when, with your time zone; the full error text or a screenshot, and what you expected; and your setup (the output of uv run optionspace --version, your operating system, and for MCP the client name and whether its connection check succeeds).

Never include your API key, authorization header or credential-store file. Review terminal screenshots before sharing them. A public key ID may help identify a key without exposing its secret.