Troubleshooting

​

CLI Issues

​

stac: command not found

1. Reinstall the CLI:

curl -fsSL https://raw.githubusercontent.com/StacDev/install/main/install.sh | bash

irm https://raw.githubusercontent.com/StacDev/install/main/install.ps1 | iex

2. Restart your terminal
3. Verify installation: stac --version

​

stac login fails

• 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

• 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

• 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

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)

// 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

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

1. Check action type spelling:

// Correct
"actionType": "navigate"

// Wrong
"type": "navigate"
"action": "navigate"

2. Verify action structure:

StacElevatedButton(
  child: StacText(data: 'Click'),
  onPressed: StacNavigateAction(routeName: '/next'), // Action object, not string
)

3. Check if the widget supports the action property: Not all widgets support onPressed, onTap, etc.

​

State not updating

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

2. Check placeholder syntax:

'{{key}}'     // Correct
'{ {key} }'   // Wrong - no spaces
'{key}'       // Wrong - need double braces

​

Network Issues

​

Network request fails

1. Check URL format:

StacNetworkRequest(
  url: 'https://api.example.com/data', // Full URL with protocol
  method: Method.get,
)

2. Verify headers:

StacNetworkRequest(
  url: 'https://api.example.com/data',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json',
  },
)

3. Handle all status codes:

results: [
  StacNetworkResult(statusCode: 200, action: successAction),
  StacNetworkResult(statusCode: 401, action: unauthorizedAction),
  StacNetworkResult(statusCode: 500, action: errorAction),
]

​

CORS errors (web)

• 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

1. Missing imports:

import 'package:stac/stac_core.dart'; // Add this

2. Trailing commas: Dart benefits from trailing commas:

StacColumn(
  children: [
    StacText(data: 'Item 1'), // Trailing comma
    StacText(data: 'Item 2'), // Trailing comma
  ], // Trailing comma
)

3. Run flutter pub get to ensure dependencies are resolved

​

Generated JSON differs from expected

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

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

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

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

​

Related

• Quickstart Guide
• CLI Reference
• Project Structure