Troubleshooting

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

CLI Issues

<AccordionGroup>

hubify: command not found

The CLI is not in your PATH. Fix depends on your install method:

# 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

Authentication expired

Tokens expire periodically. Re-authenticate:

hubify auth login

For CI environments, create a long-lived token:

hubify auth token --create --name "ci" --ttl 90d

Wrong lab selected

Commands run against the active lab. Switch labs:

# Check current lab
hubify lab info

# Switch
hubify lab use correct-lab-slug

# Or override per-command
hubify experiment list --lab correct-lab-slug

Network timeout errors

The CLI communicates with api.hubify.com over HTTPS. Check your network:

curl -I https://api.hubify.com/v1/health

If behind a proxy:

export HTTPS_PROXY=https://proxy.example.com:8080

</AccordionGroup>

Agent Issues

<AccordionGroup>

Agent stuck or unresponsive

Check agent status:

hubify agent list

If an agent shows as stuck, restart it:

hubify agent update "Research Lead" --status active

Cross-model review failing

Verify external API keys are configured:

hubify agent review-config --show

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

hubify agent review-config --add-reviewer gpt-5.4 --api-key $NEW_OPENAI_KEY

Orchestrator not routing tasks

Ensure auto-scheduling is enabled:

hubify agent update orchestrator --auto-schedule true

Check if the orchestrator is overloaded:

hubify agent metrics orchestrator

</AccordionGroup>

Compute Issues

<AccordionGroup>

Pod stuck in provisioning

The requested GPU may be out of stock. Check availability:

hubify pod list --available

Try a different GPU type or region:

hubify experiment rerun EXP-051 --override "pod=a100"

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:

model.gradient_checkpointing_enable()

Idle pod wasting money

Find and terminate idle pods:

hubify pod list --json | jq '.[] | select(.status=="idle")'
hubify pod stop pod-idle-123

Prevent future waste by setting an idle timeout:

hubify pod config --idle-timeout 15m

Budget limit reached

When the monthly budget is hit, new experiments queue instead of launching:

# Check budget
hubify pod budget --show

# Increase limit
hubify pod budget --monthly 750

# Or wait until next month

</AccordionGroup>

Paper Issues

<AccordionGroup>

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:

hubify paper compile paper-1 --check

If the PDF is under 1 MB, figures are not embedded.

Undefined references in PDF

Run compilation multiple times (the compile command does this automatically):

hubify paper compile paper-1

If references persist, check that all \cite{} keys exist in your .bib file.

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:

hubify paper compile paper-1 --verbose

</AccordionGroup>

Lab Site Issues

<AccordionGroup>

Site not updating after experiment

Force a sync and redeploy:

hubify site sync
hubify site deploy

Custom domain not working

Verify DNS and SSL:

hubify site domain --status

Ensure your CNAME record points to cname.hubify.app. SSL provisioning takes 1-5 minutes.

</AccordionGroup>

Getting Help

If your issue is not listed here:

# 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"