/debugging-workflows

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.
version: 1.7.1
updated: 2026-11-10
tags: [foundry, debugging, cli, deployment, artifacts, functions, logs, execution]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: troubleshooting

Foundry Debugging Workflows

Systematic procedures for diagnosing and resolving common CrowdStrike Falcon Foundry development issues.

> **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.

Quick Diagnosis

What's happening?

CLI command hangs
├── In headless/CI environment → Missing --no-prompt or required flags (see Headless section)
└── In interactive terminal   → Check network/auth with foundry profile list

Deploy fails
├── Validation error → Check manifest YAML syntax, then deploy again
├── "Unknown error"  → Duplicate workflow name across apps in tenant
├── "no deployable artifacts found" → Diff is only manifest/logo/metadata; deploy needs an artifact change (function/collection/UI/agent). No --force; bundle it or put the logo in the first deploy
├── "Failed" with no reason in the CLI → Falcon console: App manager > app > "Show errors (N)" (per capability)
├── validate says "deployment is currently in progress" → A deploy is still running; poll list-deployments, then retry
├── validate or deploy says "no changes detected" → No packaged file changed since the last deploy (still true right after a failed one). Change a file the deploy packages, not one in ignored:
└── Silent failure   → Tenant may be missing required module (SKU) for requested scopes

foundry ui run fails
├── On new app              → Deploy backend capabilities first (API integrations, functions, collections resolve from cloud)
├── Permission errors       → Check manifest OAuth scopes, restart server, verify auth
└── Blank page / CORS error → noAttr() or base path removed from vite.config.js (see ui-development)

Released change doesn't show
└── UI fix missing from the app → Grep the built dist; rebuild if it's absent (see Confirm a Fix Is in the Built Bundle)

Function execution fails
├── Status 500 + "Server Error"  → Check function logs: foundry functions logs <exec_id>
├── Status 202 + no result       → Async execution: foundry functions exec status <exec_id>
├── 403 "app is not installed"   → Deployed but not released + installed from App Catalog; FalconPy calls need an installed app
├── 401 on every FalconPy call, scopes correct → Client constructed at module scope; move it inside the handler
├── "authorization failed"       → Confirm the CLI profile's API client has Apps read + write; if it does, it's a platform permission problem: report the trace ID, don't edit scopes
├── "artifact is not deployed"   → Deploy first: foundry apps deploy --no-prompt
├── 404 "no app artifacts found of type FAAS_FUNCTION" right after a deploy → Pin the deployment: add --version <the version deploy printed>, e.g. --version v0.0.4-pre-release
├── No logs available            → Wait 5-10 min, then: foundry functions logs <exec_id> --refresh
│   └── Still "Log query failed"   → Temporarily return the diagnostic values in the handler's response body, deploy a pre-release (don't release it), exec once, then remove them and deploy again so the latest deployment matches the code
├── UI page: repeated 404s on /api2/faas-gateway/entities/execution/v1 in the browser console → foundry-js polling for the cloud-function result before it is ready; non-fatal if the data still loads, not a failure
└── Unexpected response          → Read logs + source, correlate timestamps against handler code

Auth fails
├── 401/403 from API   → Check OAuth scopes in manifest
├── 403 "access denied, scope not permitted" for every input → The identity making the call lacks the scope (see Which Identity Makes the Call)
├── 404 or 400 after adding scopes, other than "no app artifacts found" → An input error (name, ID, or search domain), not a permission problem. Read the error message
├── Login hangs        → Headless environment, no browser — use env vars or profile create --no-prompt
└── Works locally, fails in CI → Set FOUNDRY_API_CLIENT_ID env vars in CI config

Which Identity Makes the Call

Three identities can look alike, and each has its own scopes:

| Identity | Used by | Scopes come from | |----------|---------|------------------| | The CLI profile (`foundry profile list` shows it) | `deploy`, `release`, and starting an `exec` or `test` run | The API client in the profile | | Any other API client you hold | FalconPy scripts and MCP servers run on your machine | That API client | | The installed app | Deployed functions, including their FalconPy calls under `exec` and `test` | `auth.scopes` in `manifest.yml`, accepted when the app is installed or updated |

Granting a scope to an API client doesn't change what a function can do, even under `exec`. Add the scope to `auth.scopes`, deploy, release, and have the app's users accept the update. Until the update is accepted in the App Catalog, the call keeps answering `403`. The CLI can't list a client's scopes, so test a scope by making the call. Don't test with Hosts `query_devices_by_filter`, which has answered `200` with no declared scope.

One exception to the 403 rule above: the Falcon Next-Gen SIEM queryjobs API also answers 403 for a real repository it won't search, such as `fusion`,