feat: apify diagnose — AI reads cloud run error logs and suggests fixes #1442

Problem

When an Actor run fails on Apify, the debugging workflow today is:

1. apify run logs <runId> — pipe raw logs to terminal (often thousands of lines)
2. Manually scan for errors
3. Google the error message
4. Try a fix, apify push, wait for cloud build, run again

This is slow and requires expertise in both the Actor runtime and the Apify platform.

Note: This is a follow-on to #1366 (apify actors doctor) which handles local, offline pre-flight checks. This issue is about cloud run failures — a different problem requiring different tooling.

Proposal

Add an AI-powered command that fetches the most recent (or specified) run logs and surfaces a diagnosis:

apify diagnose [--run <runId>]

What it does

1. Fetches the failed run's logs from the Apify API (defaults to the last failed run of the Actor in the current directory)
2. Extracts the error section (stack trace, last N lines, exit code)
3. Sends to an LLM with context about the Actor type, runtime, and common failure patterns
4. Prints a structured diagnosis with suggested fixes

Example output

$ apify diagnose

Fetching last failed run for "my-scraper" (run ID: abc123)...
Run status: FAILED  |  Exit code: 1  |  Duration: 42s

── Diagnosis ─────────────────────────────────────────────────

Error: Navigation timeout exceeded (30000ms)
  at src/main.js:47

Likely cause:
  The target page (https://example.com/products) is JS-heavy and
  took longer than Playwright's default 30s navigation timeout.

Suggested fix:
  Increase the timeout in your Playwright launch options:

    const page = await browser.newPage();
    await page.goto(url, { timeout: 60000 });  // increase from 30s

  Or enable request interception to block heavy resources:
    await page.route('**/*.{png,jpg,css,font}', r => r.abort());

Docs: https://docs.apify.com/sdk/js/docs/guides/playwright-crawler

── Raw log tail (last 20 lines) ─────────────────────────────
...

Why it matters

• Reduces support burden: common errors get instant diagnoses without filing a ticket
• Speeds up the Actor development loop (push → fail → diagnose → fix in minutes, not hours)
• Especially valuable for new developers who don't know Apify internals
• Complements apify actors doctor (feat: Add apify actors doctor for local Actor project diagnostics #1366) to give end-to-end coverage: local issues caught before push, cloud issues diagnosed after

Open questions

• Which LLM / API (Apify-hosted vs user brings key)?
• Support for apify diagnose --build <buildId> to diagnose build failures too?
• Should it offer to apply the fix automatically (edit the file)?

Related

• feat: Add apify actors doctor for local Actor project diagnostics #1366 — apify actors doctor (offline local pre-flight checks — ship first)
• Better error messages with fix suggestions and docs links #1063 — Better error messages with fix suggestions and docs links
• apify run: detect Playwright base image + missing local browser, direct user to remote or Docker fallback #1258 — apify run: detect Playwright base image + missing local browser