> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodepick.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Common Nodepick Errors and API Issues

> Solutions to common Nodepick issues including authentication errors, node provisioning failures, SSH connection problems, and API errors.

Most issues you encounter with Nodepick fall into a small set of well-understood categories. This guide covers the most common problems — from authentication failures to unexpected billing — and gives you concrete steps to resolve each one. Work through the relevant section below, and if you're still stuck, reach out to the support team.

<AccordionGroup>
  <Accordion title="401 Unauthorized — API key rejected">
    A `401 Unauthorized` response means the API could not verify your identity. This is almost always caused by a misconfigured or missing API key.

    **Steps to resolve:**

    1. **Check for extra whitespace.** Copy-paste errors often introduce a leading or trailing space. Make sure your key contains no extra characters.

    2. **Verify the Bearer token format.** Your `Authorization` header must follow this exact format:

       ```bash theme={null}
       Authorization: Bearer YOUR_API_KEY
       ```

       A common mistake is omitting the `Bearer ` prefix or using a different scheme such as `Token`.

    3. **Confirm the key is active.** Log in to your dashboard, navigate to **Developer Settings**, and verify the key hasn't been revoked. If in doubt, regenerate a new key and update your environment.

    4. **Check your environment variable.** If you're loading the key from an environment variable, confirm it's set in the current shell session:

       ```bash theme={null}
       echo $NODEPICK_API_KEY
       ```
  </Accordion>

  <Accordion title="Node is stuck in 'provisioning' status">
    Nodepick nodes typically reach `running` status in under 30 seconds. If your node remains in `provisioning` longer than expected, follow these steps.

    **Steps to resolve:**

    1. **Wait and refresh.** Poll the node details endpoint again after a few seconds — the status update may simply be delayed:

       ```python theme={null}
       import time
       details = client.get_node_details(node_id)
       print(details["status"])
       ```

    2. **Allow up to 2 minutes.** Occasional infrastructure delays can extend provisioning time. If the status transitions to `running` within 2 minutes, no action is needed.

    3. **Delete and recreate the node.** If the node is still in `provisioning` after 2 minutes, delete it and provision a new one:

       ```python theme={null}
       client.delete_node(node_id)
       node = client.create_node()
       ```

    4. **Contact support.** If the problem happens repeatedly, reach out via the dashboard. Include the node ID so the team can investigate.
  </Accordion>

  <Accordion title="Cannot connect via SSH">
    SSH connection failures are usually caused by connecting too early or using incorrect connection details.

    **Steps to resolve:**

    1. **Check node status first.** SSH is only available once the node status is `running`. Attempting to connect during provisioning will time out:

       ```python theme={null}
       details = client.get_node_details(node_id)
       print(details["status"])  # Must be "running"
       ```

    2. **Use the IP address from node details.** Always retrieve the IP address directly from the API rather than caching it — it won't change, but this rules out stale data:

       ```bash theme={null}
       ssh root@<ip_address>
       ```

       Replace `<ip_address>` with the value of `details["ip_address"]`.

    3. **Check your local firewall.** Make sure your machine or network isn't blocking outbound connections on port 22. Test with:

       ```bash theme={null}
       nc -zv <ip_address> 22
       ```

    4. **Confirm a routable IP is assigned.** If `ip_address` is missing or null in the node details response, the node may not have finished initializing. Wait a few seconds and poll again.
  </Accordion>

  <Accordion title="Node was deleted unexpectedly">
    If a node disappears without you explicitly deleting it, there are a few likely explanations.

    **Steps to resolve:**

    1. **Check for shared API key usage.** If your API key is used by a teammate, a shared script, or a CI/CD system, another process may have called `DELETE /nodes/{id}`. Review recent activity in the dashboard.

    2. **Review your AI assistant history.** If you use Nodepick's agentic assistant or have integrated an AI tool with your API key, check its action history — it may have deleted the node as part of a cleanup step.

    3. **Search your codebase for cleanup logic.** Look for `delete_node()` or `DELETE /nodes` calls in scripts that might run automatically, such as shutdown hooks, test teardown functions, or scheduled jobs.

    4. **Recreate the node as needed.** Deleted nodes cannot be recovered. Provision a fresh one and resume your work:

       ```python theme={null}
       node = client.create_node()
       ```
  </Accordion>

  <Accordion title="Python SDK import error">
    If Python raises a `ModuleNotFoundError` or `ImportError` when importing `nodepick`, the package isn't installed in the Python environment you're using.

    **Steps to resolve:**

    1. **Install the package** in your current environment:

       ```bash theme={null}
       pip install nodepick
       ```

    2. **Check your active environment.** If you use virtual environments or conda, make sure the correct one is activated before installing and running your script:

       ```bash theme={null}
       which python
       which pip
       ```

    3. **Verify Python version compatibility.** The SDK requires Python 3.7 or later. Check your version with:

       ```bash theme={null}
       python --version
       ```

    4. **Upgrade to the latest version** if you have an older install:

       ```bash theme={null}
       pip install --upgrade nodepick
       ```
  </Accordion>

  <Accordion title="Unexpected billing charges">
    Nodepick charges per second from the moment a node is created until it is deleted. Unexpected charges usually mean nodes were left running after your script exited.

    **Steps to resolve:**

    1. **Audit your active nodes.** Use the list endpoint to see every node currently running on your account:

       ```bash theme={null}
       curl -X GET https://api.nodepick.ai/nodes \
         -H "Authorization: Bearer YOUR_API_KEY"
       ```

       Delete any nodes you no longer need.

    2. **Check scripts that create nodes.** Look for code paths that call `create_node()` but may not reach the corresponding `delete_node()` — for example, if an exception is raised mid-script.

    3. **Use `try/finally` to guarantee cleanup.** Wrap your node lifecycle in a `try/finally` block so deletion always runs, even on error:

       ```python theme={null}
       node = client.create_node()
       node_id = node["id"]
       try:
           # Your workload here
           pass
       finally:
           client.delete_node(node_id)
           print("Node deleted — billing stopped")
       ```

    4. **Prefer the context manager pattern.** Using `with nodepick(...) as client:` ensures `client.close()` is always called, and pairing it with explicit `delete_node()` calls inside the block prevents runaway nodes.
  </Accordion>
</AccordionGroup>

<Info>
  If your issue isn't covered here, you can reach the Nodepick support team directly through the dashboard or by visiting [https://www.nodepick.ai](https://www.nodepick.ai).
</Info>