# FAQ

## Installation and authentication

### Empty model list during `/login`

If you see "No models available for the selected platform" error when running the `/login` (or `/setup`) command, it may be due to:

- **Invalid or expired API key**: Check if your API key is correct and still valid.
- **Network connection issues**: Confirm you can access the API service addresses (such as `api.pythinker.com` or `api.pythinker-ai.cn`).

### Invalid API key

Possible reasons for an invalid API key:

- **Key input error**: Check for extra spaces or missing characters.
- **Key expired or revoked**: Confirm the key status in the platform console.
- **Environment variable override**: Check if `PYTHINKER_API_KEY` or `OPENAI_API_KEY` environment variables are overriding the key in the config file. You can run `echo $PYTHINKER_API_KEY` to check.

### Membership expired or quota exhausted

If you're using the Pythinker platform, you can check your current quota and membership status with the `/usage` command. If the quota is exhausted or membership expired, you need to renew or upgrade at [Pythinker](https://pythinker.com/coding).

## Interaction issues

### `cd` command doesn't work in shell mode

Executing the `cd` command in shell mode won't change Pythinker Code's working directory. This is because each shell command executes in an independent subprocess, and directory changes only take effect within that process.

If you need to change working directory:

- **Exit and restart**: Run the `pythinker` command again in the target directory.
- **Use `--work-dir` flag**: Specify working directory at startup, like `pythinker --work-dir /path/to/project`.
- **Use absolute paths in commands**: Execute commands with absolute paths directly, like `ls /path/to/dir`.

### Image paste fails

When using `Ctrl-V` to paste an image, if you see "Current model does not support image input", it means the current model doesn't support image input.

Solutions:

- **Switch to an image-capable model**: Use a model that supports the `image_in` capability.
- **Check clipboard content**: Make sure the clipboard contains actual image data, not just a file path to an image.

### Working directory deleted or removed

If the working directory becomes inaccessible during a session (external drive unplugged, directory deleted, or filesystem unmounted), Pythinker Code detects the situation and displays a crash report containing the session ID and work directory path, then exits cleanly. You can recover the session with `pythinker -r <session-id>` from the correct directory.

## ACP issues

### IDE cannot connect to Pythinker Code

If your IDE (like Zed or JetBrains IDEs) cannot connect to Pythinker Code, check the following:

- **Confirm Pythinker Code is installed**: Run `pythinker --version` to confirm successful installation.
- **Check configuration path**: Ensure the Pythinker Code path in IDE configuration is correct. You can typically use `pythinker acp` as the command.
- **Check uv path**: If installed via uv, ensure `~/.local/bin` is in PATH. You can use an absolute path like `/Users/yourname/.local/bin/pythinker acp`.
- **Check logs**: Examine error messages in `~/.pythinker/logs/pythinker.log`.

## MCP issues

### MCP server startup fails

After adding an MCP server, if tools aren't loaded or there are errors, it may be due to:

- **Command doesn't exist**: For stdio type servers, ensure the command (like `npx`) is in PATH. You can configure with an absolute path.
- **Configuration format error**: Check if `~/.pythinker/mcp.json` is valid JSON. Run `pythinker mcp list` to view current configuration.

Debugging steps:

```sh
# View configured servers
pythinker mcp list

# Test if server is working
pythinker mcp test <server-name>
```

### OAuth authorization fails

For MCP servers that require OAuth authorization (like Linear), if authorization fails:

- **Check network connection**: Ensure you can access the authorization server.
- **Re-authorize**: Run `pythinker mcp auth <server-name>` to authorize again.
- **Reset authorization**: If authorization info is corrupted, run `pythinker mcp reset-auth <server-name>` to clear it and retry.

### Header format error

When adding HTTP type MCP servers, header format should be `KEY: VALUE` (with a space after the colon). For example:

```sh
# Correct
pythinker mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: your-key"

# Wrong (missing space or using equals sign)
pythinker mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY=your-key"
```

## Print/Wire mode issues

### Invalid JSONL input format

When using `--input-format stream-json`, input must be valid JSONL (one JSON object per line). Common issues:

- **JSON format error**: Ensure each line is a complete JSON object without syntax errors.
- **Encoding issues**: Ensure input uses UTF-8 encoding.
- **Line ending issues**: Windows users should check if line endings are `\n` rather than `\r\n`.

Correct input format example:

```json
{"role": "user", "content": "Hello"}
```

### No output in print mode

If there's no output in `--print` mode, it may be:

- **No input provided**: You need to provide input via `--prompt` (or `--command`) or stdin. For example: `pythinker --print --prompt "Hello"`.
- **Output is buffered**: Try using `--output-format stream-json` for streaming output.
- **Configuration incomplete**: Ensure API key and model are configured via `/login`.

## Updates and upgrades

### macOS slow first run

macOS's Gatekeeper security mechanism checks new programs on first run, causing slow startup. Solutions:

- **Wait for check to complete**: Be patient on first run; subsequent launches will return to normal.
- **Add to Developer Tools**: Add your terminal application in "System Settings → Privacy & Security → Developer Tools".

### How to upgrade Pythinker Code

Run the built-in updater from any install method:

```sh
pythinker update
```

Inside the interactive shell, use `/update`. Pythinker checks the matching channel for your install (native installer, Homebrew, or PyPI) before offering the update.

### Update notice on startup

Startup is non-blocking. When a newer installable version is detected by the background check, Pythinker Code shows a short update notice in the shell; run `/update` when you are ready.

### How to disable update reminders

If you don't want Pythinker Code to check for updates or show startup update notices, set the environment variable:

```sh
export PYTHINKER_CLI_NO_AUTO_UPDATE=1
```

This disables background update checks and startup update notices. You can add this line to your shell configuration file (like `~/.zshrc` or `~/.bashrc`).
