{"id":18978,"plugin_id":"plugins_6a8f6d7f7fac819191e3eba5a7a2e0df","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:15:07.639Z","digest":"b2b78344f3b0ce1fdae1ad845decef441b59b0c3b691706f18cecfa053550b0e","against":null,"payload":{"name":"debugging-workflows","description":"Systematic troubleshooting for Falcon Foundry CLI errors, manifest validation failures, deploy failures, artifact runtime errors, and development server issues. TRIGGER when user encounters CLI errors, `foundry ui run` not working, deploy failures, authentication issues, function execution failures, \"debug my function\", \"why did this fail\", or any unexpected behavior during Foundry app development. Also trigger for headless/CI environment setup failures.","included_files":[],"skill_md_contents":"---\nname: debugging-workflows\ndescription: Systematic troubleshooting for Falcon Foundry CLI errors, manifest validation failures, deploy failures, artifact runtime errors, and development server issues. TRIGGER when user encounters CLI errors, `foundry ui run` not working, deploy failures, authentication issues, function execution failures, \"debug my function\", \"why did this fail\", or any unexpected behavior during Foundry app development. Also trigger for headless/CI environment setup failures.\nversion: 1.5.0\nupdated: 2026-08-19\ntags: [foundry, debugging, cli, deployment, artifacts, functions, logs, execution]\nauthor: CrowdStrike\nlicense: MIT\ncompatibility: Claude Code >=1.0\nmetadata:\n  category: troubleshooting\n---\n\n# Foundry Debugging Workflows\n\nSystematic procedures for diagnosing and resolving common CrowdStrike Falcon Foundry development issues.\n\n> **Part of a suite.** If `development-workflow` has not already run, and this is a new app or its first capability, load the `development-workflow` skill first — it owns the CLI prerequisite check, scaffolding order, and manifest coordination.\n\n## Quick Diagnosis\n\n```\nWhat's happening?\n\nCLI command hangs\n├── In headless/CI environment → Missing --no-prompt or required flags (see Headless section)\n└── In interactive terminal   → Check network/auth with foundry profile active\n\nDeploy fails\n├── Validation error → Check manifest YAML syntax, then deploy again\n├── \"Unknown error\"  → Duplicate workflow name across apps in tenant\n└── Silent failure   → Tenant may be missing required module (SKU) for requested scopes\n\nfoundry ui run fails\n├── On new app              → Deploy backend capabilities first (API integrations, functions, collections resolve from cloud)\n├── Permission errors       → Check manifest OAuth scopes, restart server, verify auth\n└── Blank page / CORS error → noAttr() or base path removed from vite.config.js (see ui-development)\n\nFunction execution fails\n├── Status 500 + \"Server Error\"  → Check function logs: foundry functions logs <exec_id>\n├── Status 202 + no result       → Async execution: foundry functions exec status <exec_id>\n├── \"authorization failed\"       → Missing custom-apps:write scope on API client\n├── \"artifact is not deployed\"   → Deploy first: foundry apps deploy --no-prompt\n├── No logs available            → Wait ~5 min, then: foundry functions logs <exec_id> --refresh\n└── Unexpected response          → Read logs + source, correlate timestamps against handler code\n\nAuth fails\n├── 401/403 from API   → Check OAuth scopes in manifest\n├── Login hangs        → Headless environment, no browser — use env vars or profile create --no-prompt\n└── Works locally, fails in CI → Set FOUNDRY_API_CLIENT_ID env vars in CI config\n```\n\n## Local Testing\n\n### Function Testing\n\n```bash\n# Via Foundry CLI with Docker (random ports, closest to production)\nfoundry functions run --name my-function\n\n# Direct Go execution (port 8081, no Docker)\ncd functions/my-function && go run main.go\n\n# Direct Python execution (port 8081, no Docker)\ncd functions/my-function && python3 main.py\ncurl -X POST http://localhost:8081/api/process -d '{\"key\":\"value\"}'\n\n# With configuration file (local only)\nCS_FN_CONFIG_PATH=./config.json python3 main.py\n```\n\n### Function Execution & Log Retrieval (Deployed Functions)\n\n> **Requires Foundry CLI 2.1.0+.** These commands do not exist in CLI 2.0.x.\n\nFor testing against the deployed Lambda (not local Docker), use the execution commands:\n\n```bash\n# Execute a deployed function handler\nfoundry functions exec --handler my_handler '{\"key\": \"value\"}' --no-prompt\n\n# Execute and wait for logs\nfoundry functions exec --handler my_handler --logs '{\"payload\": \"data\"}' --no-prompt\n\n# Check status of an async (202) execution\nfoundry functions exec status <exec_id>\n\n# Retrieve logs for a past execution\nfoundry functions logs <exec_id>\n\n# List recent executions to find one to debug\nfoundry functions exec list --function my-fn --no-prompt\n```\n\n### Function Runtime Debugging\n\nWhen a deployed function returns unexpected results or errors:\n\n**Step 1: Execute and observe**\n```bash\nfoundry functions exec --handler <handler> --logs '{\"test\": \"input\"}' --no-prompt\n```\n\nNote the exec_id and status code from the output.\n\n**Step 2: Retrieve logs if not already displayed**\n```bash\nfoundry functions logs <exec_id>\n```\n\nLogs arrive ~5 minutes after execution via the Firehose pipeline. The CLI polls automatically with a countdown.\n\n**Step 3: Correlate logs against source**\n\nThe function source lives at the path in `manifest.yml`:\n```yaml\nfunctions:\n  - name: my-function\n    path: functions/my-function\n    handlers:\n      - name: my_handler\n        method: POST\n        api_path: /api/process\n```\n\nRead the handler source and compare against log timestamps and error messages.\n\n**Step 4: Common runtime failures**\n\n| Log Pattern | Likely Cause | Fix |\n|-------------|-------------|-----|\n| `ImportError: No module named X` | Missing from `requirements.txt` | Add dependency, redeploy |\n| `KeyError: 'field'` | Missing field in request body | Add input validation |\n| `401 Unauthorized` from FalconPy | Missing OAuth scope in manifest | Add scope, redeploy |\n| `Timeout` / no logs appear | Function exceeded `max_exec_duration_seconds` | Increase timeout or optimize |\n| Status 202, no result | Async execution | Poll: `foundry functions exec status <exec_id>` |\n| Logs say \"available\" but empty | Logs not yet in pipeline | Wait 5 min or use `--refresh` |\n\n**Step 5: Fix, redeploy, verify**\n```bash\n# After fixing the code:\nfoundry apps deploy --change-type Patch --change-log \"fix handler error\" --no-prompt\n\n# Re-execute to verify\nfoundry functions exec --handler <handler> --logs '{\"test\": \"input\"}' --no-prompt\n```\n\n### RTR Script Testing\n\nRTR scripts can only be tested via the CLI (not the Falcon console):\n\n```bash\nfoundry rtr-scripts run --name my-script\n```\n\nPlatforms: Windows (`script.ps1`), Linux (`script.sh`), macOS (`script.zsh`). Script size limit ~40KB. Deletion requires Falcon Administrator role in Falcon console UI.\n\n### Workflow Mock Testing\n\n```bash\nfoundry workflows triggers view --mock\nfoundry workflows actions view --mock\nfoundry workflows executions validate --mocks mymocks.json\nfoundry workflows executions start --definition my-workflow --mocks mymocks.json\nfoundry workflows executions view <execution_id>\n```\n\n### Deployment Diagnostics\n\nDeployment is two-phase: validation (checks manifest and schemas) then artifact build. Use `foundry apps validate --no-prompt` to dry-run the validation phase after adding API integrations or collections (catches spec/schema issues in seconds). Don't validate right before deploy — deploy runs the same validation plus workflow semantics and name uniqueness checks.\n\n## CLI Troubleshooting\n\n### Step 1: Environment Validation\n\n```bash\nfoundry version         # Check CLI version\nfoundry profile list    # Check available profiles\nfoundry profile active  # Verify active profile\n```\n\n### Step 2: Authentication\n\n```bash\nfoundry login                                    # Re-authenticate via browser (interactive)\nfoundry profile delete --name <name> --no-prompt # Reset corrupted profile\nfoundry login                                    # Re-authenticate\n```\n\n### `connection issue` on Tenant Commands (Sandboxed Agents)\n\n**Check the token cache write first — it is the usual cause and it is not a network problem.**\n\nThe CLI keeps its short-lived access token in `~/.config/foundry/token.json`, separate from the credentials in `configuration.yml`. The token lasts about 30 minutes, and the next tenant command after it expires writes a fresh one back to that file. That write is expected and is the safer design: a rotating 30-minute token beats a long-lived one, and keeping it out of the workspace means it never gets committed.\n\nAssistants that confine writes to the workspace are denied that write, and the CLI reports only `connection issue` — the symptom, not the cause. Since a session usually begins with an already-expired token, this appears within the first few seconds, not after half an hour.\n\nFix: **request write access to `~/.config/foundry/` and retry the same command.** Say why — the CLI is refreshing its own token cache — and treat it as a routine low-risk escalation rather than a blocker. Do not ask the user to relaunch their assistant, and do not rewrite the profile, redirect the config path into the workspace, or copy credentials; those hide working credentials instead of granting the one needed write.\n\nIf the write succeeds and tenant commands still fail, then treat it as network: ask the user to run the command in their own terminal, and if it works there, request unsandboxed network access and retry once.\n\n### Manifest Validation\n\nUse `foundry apps validate --no-prompt` to validate the manifest and schemas without deploying. For OpenAPI specs, use `npx @redocly/cli lint` to validate structure locally.\n\nIf deploy fails with validation errors:\n1. Check the error message — validation errors appear first\n2. Comment out capabilities one by one to isolate the issue\n3. Fix and re-validate incrementally\n\n## Headless / Non-Interactive Environments\n\nThis is the most common failure mode when Foundry CLI is driven by agents (Claude Code) or CI/CD pipelines. Most commands default to interactive mode, which blocks indefinitely.\n\n### `foundry login` Hangs or Fails\n\n`foundry login` opens a browser for OAuth. In headless environments, use one of these alternatives:\n\n**Option 1: Environment variables** (no login needed):\n```bash\nexport FOUNDRY_API_CLIENT_ID=\"<client-id>\"\nexport FOUNDRY_API_CLIENT_SECRET=\"<client-secret>\"\nexport FOUNDRY_CID=\"<customer-id>\"\nexport FOUNDRY_CLOUD_REGION=\"us-1\"\n```\n\n**Option 2: Non-interactive profile creation**:\n```bash\nfoundry profile create \\\n  --name \"ci-profile\" \\\n  --api-client-id \"<id>\" \\\n  --api-client-secret \"<secret>\" \\\n  --cid \"<cid>\" \\\n  --cloud-region \"us-1\" \\\n  --no-prompt\nfoundry profile activate --name \"ci-profile\"\n```\n\n**Option 3: Pre-populated config file** at `~/.config/foundry/configuration.yml`:\n```yaml\nprofiles:\n- name: ci-profile\n  cloud_region: us-1\n  credentials:\n    cid: <customer-id>\n    api_client_id: <client-id>\n    api_client_secret: <client-secret>\nactive_profile: ci-profile\n```\n\n### Command Hangs Waiting for Input\n\nAdd `--no-prompt` to prevent interactive prompts. Nearly all commands support it: `apps create`, `apps validate`, `apps deploy`, `apps release`, `apps delete` (also needs `--force-delete`), `functions create`, `collections create`, `ui pages create`, `ui extensions create`, `rtr-scripts create`, `profile create`, `profile delete`, `workflows create`, and `api-integrations create`. Provide all required flags explicitly — run `foundry <command> --help` to identify them.\n\n### Auth Works Locally but Fails in CI\n\nThe CI environment has no `~/.config/foundry/configuration.yml`. Set environment variables in CI pipeline configuration — they override local config.\n\n## Common Issue Patterns\n\n| Symptom | Likely Cause | First Action |\n|---------|--------------|--------------|\n| `foundry login` hangs | Headless environment | Use env vars or `profile create --no-prompt` |\n| Any command hangs | Missing `--no-prompt` or required flags | Add flags, run `--help` |\n| Deploy hangs indefinitely | Manifest validation issue | Check YAML syntax, deploy again |\n| `foundry ui run` fails on new app | Backend not deployed | Run `foundry apps deploy` first |\n| API calls return 403 | Insufficient OAuth scopes | Review manifest oauth section |\n| Deploy fails silently | Tenant missing required module (SKU) | Verify tenant has Falcon module for scopes |\n| Local server won't start | Port conflicts | Use `--port` flag or kill existing processes |\n| Auth works locally, fails in CI | No config file in CI | Set `FOUNDRY_API_CLIENT_ID` env vars |\n| `connection issue` in a sandboxed agent | Denied write to the CLI's token cache | Grant write to `~/.config/foundry/`; the token refresh is expected |\n| Tenant command works for user, not agent | Agent network sandbox | Request elevation, then retry once |\n| Page 404 after deploy/release | App not installed from App Catalog | Install from catalog, wait for propagation |\n| Page 404 on new cloud only | Cloud-specific IDs in manifest | Strip IDs with yq before deploying to new cloud |\n| Blank page, no CORS errors | Vite `root` changed from `src` | Restore `root: 'src'` in vite.config.js |\n| Blank page with CORS errors | `noAttr()` removed from vite.config.js | Restore the `noAttr()` plugin in vite.config.js |\n| Blank page, no errors in console | `falcon.connect()` not awaited | The platform iframe stays blank until the postMessage handshake completes — add `await falcon.connect()` before any rendering |\n| Data not appearing after writes | Schema mismatch or missing error check | Verify field names/enums match schema exactly; check `result?.errors?.length` after writes |\n| Dialog white background in dark mode | Shoelace panel defaults | Override `--sl-panel-background-color` with `var(--ground-floor)` |\n| App install fails with no detail | Workflow CEL expression error | Test API integration in console, then inspect workflow editor for errors |\n\n## Debugging App Install Failures\n\nWhen a Foundry app fails to install with no useful error message, isolate the problem by testing each component in the Falcon console:\n\n1. **Test the API integration first** — In the Falcon console, use the credentials from the install config to test the operation directly (e.g., run `listUsers` with the Okta domain and API key). This proves whether the spec and credentials work independently of the app.\n\n2. **Eliminate unlikely suspects** — Static UI files (extensions, pages) don't cause install failures. If the API integration works, the problem is almost certainly in a workflow.\n\n3. **Inspect the workflow in the console** — Open Falcon Fusion SOAR, edit the workflow, and look at each action's configuration. The workflow editor shows validation errors (like unknown variable references in CEL expressions) that the install API doesn't surface.\n\n> **Example:** Apps failed to install with no detail. API integration tested fine. Editing the workflow in the console revealed \"unknown variable\" on the Print data action — the CEL variable path was missing the `Custom_` prefix the platform adds to all API integration names. The install error gave no hint; the workflow editor showed it immediately.\n\n## Visual Debugging with Screenshots\n\nClaude Code can read images directly. When the Falcon console shows something unexpected — a blank page, an error modal, a disabled button — a screenshot is often the fastest way to diagnose the issue.\n\n**Without Playwright MCP (fastest):** Ask the user to take a screenshot of what they're seeing and paste or drag it into the conversation. Claude reads it immediately and can identify error messages, missing elements, wrong page states, or styling issues without any setup.\n\n**With Playwright MCP:** If Playwright MCP is configured (`claude mcp add playwright -- npx @playwright/mcp@latest`), Claude can take screenshots directly via `browser_take_screenshot`. This is useful for interactive debugging sessions. See `e2e-testing/references/debugging-with-mcp.md` for details.\n\n**From test failure artifacts:** When e2e tests fail, Playwright saves screenshots to `test-results/`. Read the `.png` file directly — it shows the exact page state at the moment of failure.\n\nScreenshots are particularly effective for:\n- Blank pages after deploy (missing iframe, broken Vite config)\n- Extension buttons that don't appear or expand\n- Error banners or modals with messages not surfaced by the CLI\n- `foundry ui run` rendering issues (dark mode, missing Shoelace styles)\n- App install dialogs with unexpected form fields\n\n## Recovery Strategies\n\n### Profile Corruption\n1. Delete corrupted profile: `foundry profile delete --name <name> --no-prompt`\n2. Re-authenticate with `foundry login`\n3. Validate with test deployment\n\n### Development Server\n1. Kill existing processes: `pkill -f \"foundry ui\"`\n2. Clear node_modules and reinstall\n3. Restart with clean environment\n\n### Manifest Issues\n1. Backup current `manifest.yml`\n2. Start with minimal working manifest\n3. Incrementally add capabilities back, deploying after each addition\n\n## Pre-Escalation Checklist\n\nBefore seeking external help:\n\n- [ ] Verified CLI version with `foundry version`\n- [ ] Checked authentication with `foundry profile active`\n- [ ] Validated OpenAPI specs with `npx @redocly/cli lint` (if applicable)\n- [ ] Tested with minimal configuration\n- [ ] Reviewed CLI error messages\n- [ ] Attempted recovery procedures\n- [ ] Documented reproduction steps\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}