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

# Troubleshooting

> Common issues and fixes for Hubify Labs, CLI, agents, pods, papers, and deployments.

# Troubleshooting

Solutions for common issues across the CLI, web UI, agents, compute, and paper pipeline.

## CLI Issues

<AccordionGroup>
  <Accordion title="hubify: command not found">
    The CLI is not in your PATH. Fix depends on your install method:

    ```bash theme={null}
    # npm: add global bin to PATH
    export PATH="$(npm config get prefix)/bin:$PATH"

    # Add to your shell profile (~/.zshrc or ~/.bashrc)
    echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Accordion>

  <Accordion title="Authentication expired">
    Tokens expire periodically. Re-authenticate:

    ```bash theme={null}
    hubify auth login
    ```

    For CI environments, create a long-lived token:

    ```bash theme={null}
    hubify auth token --create --name "ci" --ttl 90d
    ```
  </Accordion>

  <Accordion title="Wrong lab selected">
    Commands run against the active lab. Switch labs:

    ```bash theme={null}
    # Check current lab
    hubify lab info

    # Switch
    hubify lab use correct-lab-slug

    # Or override per-command
    hubify experiment list --lab correct-lab-slug
    ```
  </Accordion>

  <Accordion title="Network timeout errors">
    The CLI communicates with `www.hubify.com/api` over HTTPS. Check your network:

    ```bash theme={null}
    curl -I https://www.hubify.com/api/v1/health
    ```

    If behind a proxy:

    ```bash theme={null}
    export HTTPS_PROXY=https://proxy.example.com:8080
    ```
  </Accordion>
</AccordionGroup>

## Agent Issues

<AccordionGroup>
  <Accordion title="Agent stuck or unresponsive">
    Check agent status:

    ```bash theme={null}
    hubify agent list
    ```

    If an agent shows as `stuck`, restart it:

    ```bash theme={null}
    hubify agent update "Research Lead" --status active
    ```
  </Accordion>

  <Accordion title="Cross-model review failing">
    Verify external API keys are configured:

    ```bash theme={null}
    hubify agent review-config --show
    ```

    If a provider's key is expired or invalid, update it:

    ```bash theme={null}
    hubify agent review-config --add-reviewer gpt-5.5 --api-key $NEW_OPENAI_KEY
    ```
  </Accordion>

  <Accordion title="Orchestrator not routing tasks">
    Ensure auto-scheduling is enabled:

    ```bash theme={null}
    hubify agent update orchestrator --auto-schedule true
    ```

    Check if the orchestrator is overloaded:

    ```bash theme={null}
    hubify agent metrics orchestrator
    ```
  </Accordion>
</AccordionGroup>

## Compute Issues

<AccordionGroup>
  <Accordion title="Pod stuck in provisioning">
    The requested GPU may be out of stock. Check availability:

    ```bash theme={null}
    hubify pod list --available
    ```

    Try a different GPU type or region:

    ```bash theme={null}
    hubify experiment rerun EXP-051 --override "pod=a100"
    ```
  </Accordion>

  <Accordion title="Out of memory (OOM) on GPU">
    Reduce batch size or upgrade GPU:

    * **H100** (80 GB) handles most workloads
    * **H200** (141 GB) for the largest datasets

    For PyTorch, enable gradient checkpointing to reduce memory:

    ```python theme={null}
    model.gradient_checkpointing_enable()
    ```
  </Accordion>

  <Accordion title="Idle pod wasting money">
    Find and terminate idle pods:

    ```bash theme={null}
    hubify pod list --json | jq '.[] | select(.status=="idle")'
    hubify pod stop pod-idle-123
    ```

    Prevent future waste by setting an idle timeout:

    ```bash theme={null}
    hubify pod config --idle-timeout 15m
    ```
  </Accordion>

  <Accordion title="Budget limit reached">
    When the monthly budget is hit, new experiments queue instead of launching:

    ```bash theme={null}
    # Check budget
    hubify pod budget --show

    # Increase limit
    hubify pod budget --monthly 750

    # Or wait until next month
    ```
  </Accordion>
</AccordionGroup>

## Paper Issues

<AccordionGroup>
  <Accordion title="Figures appear as empty boxes in PDF">
    Figures must be in the same directory as the `.tex` file. The compile command handles this, but verify:

    ```bash theme={null}
    hubify paper compile paper-1 --check
    ```

    If the PDF is under 1 MB, figures are not embedded.
  </Accordion>

  <Accordion title="Undefined references in PDF">
    Run compilation multiple times (the compile command does this automatically):

    ```bash theme={null}
    hubify paper compile paper-1
    ```

    If references persist, check that all `\cite{}` keys exist in your `.bib` file.
  </Accordion>

  <Accordion title="LaTeX compilation errors">
    Common issues:

    * Using `\citep`/`\citet`, use `\cite{}` with revtex4-2
    * Using `\deluxetable`, use `\begin{table}\begin{ruledtabular}\begin{tabular}`
    * Using `aastex631` class, use `revtex4-2`

    View the full compile log:

    ```bash theme={null}
    hubify paper compile paper-1 --verbose
    ```
  </Accordion>
</AccordionGroup>

## Lab Site Issues

<AccordionGroup>
  <Accordion title="Site not updating after experiment">
    Force a sync and redeploy:

    ```bash theme={null}
    hubify site sync
    hubify site deploy
    ```
  </Accordion>

  <Accordion title="Custom domain not working">
    Verify DNS and SSL:

    ```bash theme={null}
    hubify site domain --status
    ```

    Ensure your CNAME record points to `cname.hubify.app`. SSL provisioning takes 1-5 minutes.
  </Accordion>
</AccordionGroup>

## Getting Help

If your issue is not listed here:

```bash theme={null}
# Check system status
hubify status --system

# View debug logs
hubify logs --system --level debug --since "1h ago"

# Contact support
hubify support "Description of your issue"
```