Troubleshooting

Use this page when the local run succeeds but AlphaLens does not show what you expect.

Revoked or invalid API key

Symptoms:

• ALPHALENS_API_KEY mint failed.
• Not authenticated.
• Backtests run locally but do not appear in Strategy Center.

Fix:

1. Create a fresh key in Settings → API Keys.
2. Update ALPHALENS_API_KEY.
3. Run alphalens connect --api-key alens_....
4. Re-run the backtest or deployment.

Missing Pro access

API-key creation and Strategy Center are Pro features. If the API-key route is blocked, confirm the account has Pro access and sign in again.

No Strategy Center runs

Confirm you selected the Strategy Center page, not the regular account dashboard. Backtests appear as backtest:<run_id> sources and deployments appear as deployment:<deployment_id>.

Also confirm the run was launched with cloud auth:

ALPHALENS_API_KEY=alens_... alphalens run --strategy my_strategy:MyStrategy

Strategy import fails

The --strategy value must be a Python import path in module:ClassName format. Run the command from a folder where Python can import the module.

alphalens run --strategy my_strategy:MyStrategy

For a package, include the package path:

alphalens run --strategy strategies.momentum:MomentumRotation

If Python cannot import the module, fix the working directory or PYTHONPATH before debugging AlphaLens sync.

Strategy runs but does not trade

Check the strategy lifecycle first:

• initialize sets enough warmup bars.
• on_data is receiving the symbols you expect.
• Scheduled methods are firing at the intended bar time.
• Signal thresholds are actually crossed.
• set_holdings target differs from the current position.
• Paper broker credentials point to the account you are monitoring.

For hourly intraday strategies, no orders before the next scheduled execution can be correct.

Live runner waiting for bars

The live runner processes completed bars. On a 5-minute strategy, it may wait until the next completed 5-minute bar. If your strategy schedules hourly execution, telemetry may show live bars arriving before orders are expected.

Warmup takes time

Intraday strategies can seed a large history window before on_warmup_finished fires. This is normal when history_bars is high or the universe is large.

Reduce warmup time by lowering --history-bars when the strategy can safely operate with less history:

alphalens live --strategy my_strategy:MyStrategy --history-bars 5000

Telemetry sync warnings

Telemetry is best-effort. A warning from AlphaLens cloud sync should not stop the local trading loop.

If Strategy Center is stale:

1. Check the local process is still running.
2. Check ALPHALENS_API_KEY has not been revoked.
3. Confirm the deployment heartbeat is recent.
4. Restart with the same --deployment-id if you want continuity.

Missing position allocation

Position allocation needs symbol-level market values. Backtests should sync positions_value with per-symbol position data; live deployments should emit position snapshots. If only equity appears, allocation cannot be charted.