Skip to main content
This guide covers common issues you might encounter while working with Stac and how to resolve them.

​
CLI Issues

​
stac: command not found

Problem: The Stac CLI is not installed or not in your PATH. Solution:
  1. Reinstall the CLI:
curl -fsSL https://raw.githubusercontent.com/StacDev/install/main/install.sh | bash
  1. Restart your terminal
  2. Verify installation: stac --version

​
stac login fails

Problem: Authentication fails or browser doesn’t open. Solutions:
  • Ensure you have a stable internet connection
  • Try running with stac login --verbose for more details
  • Clear cached credentials: stac logout then stac login
  • Check if your firewall is blocking the authentication callback

​
stac build shows no files

Problem: Running stac build finds no Dart files to process. Solutions:
  • Ensure your files are in the stac/ folder
  • Check that files have the .dart extension
  • Verify functions have the @StacScreen annotation:
@StacScreen(screenName: 'my_screen')
StacWidget myScreen() {
  return StacText(data: 'Hello');
}

​
stac deploy permission denied

Problem: Deployment fails with permission errors. Solutions:
  • Run stac login to refresh credentials
  • Verify you have write access to the project in Stac Cloud
  • Check your project configuration in default_stac_options.dart

​
Runtime Issues

​
Widget not rendering

Problem: A widget appears blank or doesn’t show. Common causes:
  1. Missing required property: Check the widget documentation for required properties
  2. Invalid JSON syntax: Validate your JSON structure
  3. Type mismatch: Ensure property types match (e.g., double vs int)
Debug steps: 
// Add a visible fallback to identify the issue
StacContainer(
  color: StacColors.red, // Visible background
  width: 100.0,
  height: 100.0,
  child: yourWidget,
)

​
“Unknown widget type” error

Problem: Stac doesn’t recognize a widget type. Solutions:
  1. Check spelling of the type field
  2. Verify the widget is supported (see Widgets)
  3. If using a custom widget, ensure the parser is registered:
await Stac.initialize(
  options: defaultStacOptions,
  parsers: [
    MyCustomWidgetParser(), // Register your parser
  ],
);

​
Actions not firing

Problem: Button presses or gestures don’t trigger actions. Solutions:
  1. Check action type spelling:
// Correct
"actionType": "navigate"

// Wrong
"type": "navigate"
"action": "navigate"
  1. Verify action structure:
StacElevatedButton(
  child: StacText(data: 'Click'),
  onPressed: StacNavigateAction(routeName: '/next'), // Action object, not string
)
  1. Check if the widget supports the action property: Not all widgets support onPressed, onTap, etc.

​
State not updating

Problem: StacSetValueAction doesn’t update the UI. Solutions:
  1. Verify key names match:
// Setting
StacSetValueAction(values: [{'key': 'userName', 'value': 'John'}])

// Reading - must match exactly
StacText(data: 'Hello, {{userName}}!') // Correct
StacText(data: 'Hello, {{username}}!') // Wrong - case sensitive
  1. Check placeholder syntax:
'{{key}}'     // Correct
'{ {key} }'   // Wrong - no spaces
'{key}'       // Wrong - need double braces

​
Network Issues

​
Network request fails

Problem: StacNetworkRequest returns errors. Debug checklist:
  1. Check URL format:
StacNetworkRequest(
  url: 'https://api.example.com/data', // Full URL with protocol
  method: Method.get,
)
  1. Verify headers:
StacNetworkRequest(
  url: 'https://api.example.com/data',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json',
  },
)
  1. Handle all status codes:
results: [
  StacNetworkResult(statusCode: 200, action: successAction),
  StacNetworkResult(statusCode: 401, action: unauthorizedAction),
  StacNetworkResult(statusCode: 500, action: errorAction),
]

​
CORS errors (web)

Problem: Network requests fail on Flutter web due to CORS. Solutions:
  • Configure your API server to allow CORS
  • Use a proxy server during development
  • For Stac Cloud, requests are proxied automatically

​
Build Issues

​
Dart compile errors

Problem: stac build fails with Dart errors. Common fixes:
  1. Missing imports:
import 'package:stac_core/stac_core.dart'; // Add this
  1. Trailing commas: Dart benefits from trailing commas:
StacColumn(
  children: [
    StacText(data: 'Item 1'), // Trailing comma
    StacText(data: 'Item 2'), // Trailing comma
  ], // Trailing comma
)
  1. Run flutter pub get to ensure dependencies are resolved

​
Generated JSON differs from expected

Problem: The JSON output doesn’t match what you expected. Debug steps:
  1. Check stac/.build/ for generated files
  2. Compare with expected JSON structure
  3. Verify property names (Dart uses camelCase, JSON may differ)

​
Stac Cloud Issues

​
Screen not updating after deploy

Problem: App shows old content after stac deploy. Solutions:
  1. Force refresh in app: Restart the app completely
  2. Check deployment success: Look for success message in CLI
  3. Verify project ID: Ensure default_stac_options.dart has correct project ID
  4. Check cache config: If using caching, try using StacCacheStrategy.networkFirst to ensure latest content is fetched

​
”Project not found” error

Problem: CLI can’t find your Stac Cloud project. Solutions:
  1. Run stac init to reinitialize
  2. Verify project exists in console.stac.dev
  3. Check default_stac_options.dart for correct project ID

​
Getting Help

If you’re still stuck:
  1. Search existing issues: GitHub Issues
  2. Ask the community: Discord
  3. Report a bug: Create a new issue with:
    • Stac version (stac --version)
    • Flutter version (flutter --version)
    • Minimal reproduction code
    • Error messages/stack traces