FAQ

Start Here

For local commands, configure the workspace environment with ACTSPAN_PORTAL_DISABLED=1 in its .actspan.env. Run from that workspace directory and keep the selected provider credentials configured.

For a first installation, use the quickstart instead of troubleshooting from this page. When a command fails, check it in this order:

actspan init workspace.yaml
actspan validate workspace.yaml
actspan preview workspace.yaml
actspan run workspace.yaml "WORKFLOW_NAME"

Expected result: the first failing command identifies whether the problem is dependency setup, configuration, static planning, or live execution. Then use the matching question below.

What does `pricing not found` mean?

The selected catalog has no usable price for this model/request. Cost is unknown, not measured zero; a zero placeholder in older output is not a billing result. Whether execution proceeds depends on policy and integration: mandatory estimate coverage can block dispatch. Inspect the active pricing source and cost-admission scope. Set an explicit exec.pricing_csv or use ACTSPAN_PRICING_CSV as described in the pricing reference.

How do I pass env vars without exporting them?

A: Use --set KEY=VALUE on the CLI. Example: --set SEARCH_NOTES="inspiration" --set IMAGE_URL="http://placeholder".

Where are audio/image outputs saved?

A: Use --save-audio[=path] or --save-image[=path]; by default they save next to the workflow YAML. JSON still includes URL/base64.

Why do I get “Could not find fine tune …”?

A: You’re using a key from a different org/project than the job. Use the same org key you created the job with, or re-create the job under the current key.

How do I see raw provider responses?

A: Add --verbose (alias for --include-raw) to any call command.

Validate, preview and run?

A: validate = schema/policy/pricing checks; no provider calls. preview = plan/cost estimate only. run executes the selected prompt, agent or workflow. call and setup remain compatible specialized/legacy commands.

Can preview detect a bad API key or no quota?

A: No. preview is intentionally offline, so it can detect missing secrets but not live provider state like invalid keys, revoked access, or exhausted quota. Use a live check such as:

actspan call <workspace> <target> --provider-check live --no-cache
actspan run <workspace> <target> --provider-check live --no-cache

How do I run the first example quickly?

A: Follow the two-file quickstart, then the public governed refund.

Why have both prompts and agents?

Prompts define reusable requests. Agents give runnable behavior a stable name, policy/evaluation bindings and supported runtime settings. Either can be useful: a small prompt is enough for the quickstart; an agent wrapper helps govern and reuse a behavior. Workflows connect their inputs and outputs.

Accepted schema fields are not all active controls. Agent budget_usd, step_timeout_sec and termination are declared-only; tool counts are partial, and vector memory is unimplemented. Consult the runtime support table before relying on them. Supported policy admission estimates are a separate capability.

Can Actspan create agents, or do I need LangChain/LangGraph first?

A: Actspan can create and run agents directly as YAML-defined runtime targets. You do not need to build the agent in another framework first. LangChain and LangGraph are stronger when you want code-first orchestration inside the application. Actspan is stronger when you want the agent definition, workflow, policies, evals, preview, and release evidence to be declarative and reviewable.

How do I read errors from the CLI output?

Public 0.2.0 exception: on the documented direct-prompt receipt failure, exit 0 and an outer success flag can coexist with nested execution failure. Inspect the nested status and same-run error, and consult execution status and automation. The source correction needs a separately qualified public release. Do not use this affected path as an unattended CI success gate.

A pending input/review is a pause; a completed outcome: blocked can be a valid business result. Output failure or required-reporting failure does not reverse an already committed write. Inspect its receipt before retrying.

For other paths:

Check exit code: non-zero means the CLI saw an error.
status: error → failed; success → ok (even if provider status is queued/running).
output_text: provider error message if present; if null/empty, look at raw.
error: provider error object; real messages/codes appear here; empty {} can be ignored.
raw (use --verbose): full provider payload. Example: if raw.provider_response.status is running and error is {}, it’s in progress, not failed.
Pricing warnings require policy/coverage inspection; provider errors normally set status:error and message.
Add --verbose to any call to see provider codes/messages.

What do common provider error codes mean?

model_not_found: The model name is wrong or not available to your org/key.
invalid_request_error: The request shape is invalid (missing fields, bad format, wrong file extension, unsupported parameter).
rate_limit_exceeded / billing_hard_limit_reached: You hit rate/quota/credit limits.
insufficient_quota: Same as above; add credit or reduce usage.
fine_tune_not_found: Job ID doesn’t exist for this org/key.
invalid_file_purpose / invalid_file_format: File upload purpose/format doesn’t match the operation (e.g., fine-tune requires proper JSONL).
server_error: Provider-side issue; retry later.
Empty error: {} with status queued/running: in progress; not a failure—keep polling.

How do retries work? Can I set them per provider?

Defaults: exec.retry controls backoff for all calls (call + workflow).
Per-provider override: set providers.<alias>.retry to override exec.retry for that provider only (same fields: enabled, max_attempts, initial_wait_seconds, backoff_multiplier, max_wait_seconds, jitter).
Precedence: provider retry > exec.retry > built-in defaults (3 attempts, exponential backoff).
Transient detection: rate limits, timeouts, 429/503, connection resets, etc. are retried; explicit SystemExit/schema/policy failures are not retried.

How does caching work?

Non-streaming, successful calls are cached by default under the system temp cache directory, typically .../actspan-cache/ (override with ACTSPAN_CACHE_DIR).
Key = hash of provider/model/route + the resolved request payload.
TTL = fixed 15 minutes.
Bypass with --no-cache (sets ACTSPAN_NO_CACHE=1).
We do NOT cache streaming calls or failures.
Expired or corrupt cache entries are deleted automatically when touched.
If you need caching, run without --stream; if you need a fresh call, add --no-cache.

How do output validation and repair work?

Set validate_output: true and response_format.type: json_schema on the prompt.
We strip markdown/code fences, parse the JSON, and validate against your schema.
On failure we try one feedback retry (“return ONLY valid JSON, no code fences”), then a repair call (OpenAI responses.create path).
If still invalid, we fail loud instead of returning empty/invalid output.
validate_output and the json_schema block are Actspan-only; they are removed before sending the request to the provider.

Compatibility reference: fan-out and fan-in

The fragment below requires your own declared prompts and input list; it is not a file from the public archive. Use the workflow reference for the selected authoring form. Bound the accepted collection in your application; preview estimates and declared agent budgets are not atomic fan-out caps.

Use nodes: (not legacy steps:) with depends_on to declare dependencies.
Fan-out: a node can map over a list input; it will run once per item.
Fan-in: a downstream node can depend on all mapped results; use ${results.<node_id>} to access the list.

Example:

workflows:
  - name: company_batch
    nodes:
      - id: fanout_research
        kind: prompt
        ref: company_research_prompt
        map:
          over: "${INPUT_LIST}"      # list of company names
          as: company_name
        inputs:
          INPUT_TEXT: "${company_name}"
      - id: summarize_all
        kind: prompt
        ref: summary_prompt
        depends_on: ["fanout_research"]
        inputs:
          COMPANIES_JSON: "${results.fanout_research}"
    output:
      from: summarize_all.output
      format: json

Fan-out nodes run in parallel; fan-in nodes wait for dependencies. The engine still validates DAG correctness.

FAQ