Apps Troubleshooting v2

Use this checklist when a Flowgear App does not load, invoke a Workflow, publish, or appear in a Site.

Local App does not load when debugged

  • Run the sample over HTTPS and trust its development certificate in the raw local tab before refreshing the Console debug tab.
  • Confirm FG_DEV_TENANT, FG_DEV_SITE, and FG_DEV_ENVIRONMENT identify a Site and Environment you can access.
  • Confirm the SDK initializes before the frontend renders.
  • Check the browser console for iframe, certificate, or message errors.

Context or navigation fails

Embedded context is available only through the Console host. In other words, apps can only be debugged when they're embedded via a uri like https://app.flowgear.net/#t-{tenant}}/sites/{sites}/apps/debug/?debugUrl=https%3A%2F%2Flocalhost%3A3000.

Workflow invocation fails

  • Use Flowgear.Sdk.invoke for embedded calls rather than direct fetch or axios. Direct calls will be rejected since the origin of the app is not permitted by CORS policy.
  • Use the relative HTTP path and Method from the current OpenAPI contract.
  • Confirm the selected Environment has the expected published and enabled Workflow.
  • Confirm a Cookie-based API Key targets that Environment and permits both the signed-in user and Workflow.
  • When Environment-scoped permissions are enabled, confirm the user can access that Environment.
  • Inspect Workflow logs for a reached backend; if no log exists, diagnose routing and authorization first.

A standalone App instead needs a Token-based API Key and its exact origin in Environment Allowed origins.

Package publish fails

Confirm the ZIP is no larger than 30 MB and its root contains lowercase app.json plus a supported landing page. Validate Name, changed Version, DisplayName, and nullable integer Rank. An update must use the same owning Account as the existing App.

App is missing from navigation

Confirm the package published successfully, the App is assigned to that Site, and the user has permission to list Site Apps. Assignment is independent from backend Workflow access.

Frontend and backend disagree

App packages and Workflow revisions have independent lifecycles. Refresh openapi.yml, rebuild the frontend, publish the correct Workflow revisions, and verify the selected Environment. Roll out compatible versions together.

See also

See Manage Apps Screen, App Manifest, and App Security Model.