base44-troubleshooter

Troubleshoot Production Issues

Prerequisites

Verify authentication before fetching logs:

npx base44 whoami

If not authenticated or token expired, instruct user to run npx base44 login.

Resolve app context in one of these ways:

# From a linked local project
cat base44/.app.jsonc

# Or explicitly
npx base44 logs --app-id app_123

Available Commands

Logs are not read-after-write

A single fetch that misses your run proves nothing. One-shot base44 logs reads an index that lags behind the invocation, so an empty result right after triggering a function is the expected result, not evidence of a problem.

• Live debugging: use `--follow`. Where the realtime stream is available it

delivers lines in under a second. Where it is not, the CLI says so and polls instead (Warning: Realtime logs are not available for this app — falling back to polling (lines may lag ~20-30s).). Either way --follow is the right tool — you never have to pick.

• One-shot fetches lag ~20-30s. That is ingestion time, not a filter problem.
• When output is empty, the variable to change is TIME, never a flag. Wait and

re-run the same command. Widening --limit, dropping --level, or switching --order changes nothing about a line that has not been ingested yet, and re-rolling flags is how agents talk themselves into a wrong diagnosis.

Troubleshooting Flow

1. Watch it happen — --follow

If you can trigger the failure (or it is happening now), start here rather than fetching after the fact:

npx base44 logs --follow
npx base44 logs --follow --function <function_name>

Then invoke the function and read what arrives. Rules that keep you from misreading a healthy stream:

• Never decide on a timer. Open the stream, trigger the function, and read until

you see the lines — do not read a fixed window, print, and conclude "broken". A quiet stream is quiet because nothing has been invoked.

• Delivery is per-invocation, not per-line. A long-running function's lines all

arrive when the invocation ends. Silence mid-invocation is normal.

• Redeploying mid-follow is safe. A deploy rotates the script in seconds and the

same open stream delivers the new code's lines on the next invoke. Do not tear the stream down and rebuild it after every deploy.

• `--since` is rejected with `--follow` (the stream starts from now), as are

--until and --order. For anything historical, use a one-shot fetch.

• The mode is decided once, at startup. If the first connection is refused or

unreachable, the run polls for its whole life. If the stream opens, there is no polling fallback left.

• A stream lost mid-run ends the command with `Error: The realtime log stream

stopped and could not be re-established`, exit code 1. That exit is the stream giving up, not proof that logging is broken — re-run the same command rather than changing flags.

2. Ask whether it was a scheduled run, not a request

Workflows are the automation system — cron schedules, entity triggers, connector events, in-app agent actions. When the complaint is "my scheduled job didn't run" or "the automation stopped working", function logs are the wrong tool. They show what a function printed; they cannot tell you whether a run was dispatched at all, which task inside it failed, or why the workflow stopped firing.

npx base44 workflows runs --status failed
npx base44 workflows list

A failed run carries the failing task and the underlying error, so start there and drop into base44 logs only once you know which function a failing task called. workflows list reports consecutiveFailures — anything above zero is a workflow that needs attention.

Two things that mislead here:

• `manual` in the trigger column does not mean a person clicked something. It is

what a run is stamped with when it was dispatched with no trigger type at all.

• Test runs are included, tagged next to the trigger type as (scheduled, test).

A run you fired yourself to check something will show up in the list.

3. Check Recent Errors

Start by pulling the latest errors across all functions:

npx base44 logs --level error

4. Drill Into a Specific Function

If you know which function is failing:

npx base44 logs --function <function_name> --level error

If you are outside the project directory, pass the app explicitly:

npx base44 logs --app-id app_123 --function <function_name> --level error

A --function filter is a filter on stamped rows. Apps still on the legacy per-function deployment emit unstamped rows, so a filtered view can hide them; this self-heals on the app's next deploy. If a filtered run comes back empty, re-run without --function before concluding there are no logs.

5. Inspect a Time Range

Correlate with user-reported issue timestamps:

npx base44 logs --function <function_name> --since <start_time> --until <end_time>

6. Analyze the Logs

• Look for stack traces and error messages in the output
• Check timestamps to correlate with user-reported issues
• Pass --limit explicitly to reach further back — there is no default page size, and a value above 500 is clamped down to 500

Reading an empty result

No logs found matching the filters. is ambiguous — never read it as "healthy". It means one of:

• the run has not been ingested yet (most common — wait and re-run, see above)
• no function by that name, or the filter dropped unstamped rows (see step 3)
• the app has not been published, when reading --env prod

(No production logs found. — try --env preview for draft logs)