WorkRally common pitfalls and troubleshooting

Ten frequent pitfalls

1. Using a project ID as a canvas ID
2. Hard-coding a model ID or provider
3. Constructing frontend URLs by hand
4. Calling build-draft again after canvas generation already created a node
5. Skipping asset create after upload
6. Omitting material_id or material_detail from material add
7. Putting text, freehand or generator nodes inside an artboard
8. Setting extent: "parent" on artboard children
9. Using material_id with role get
10. Using original_url for audio/video operations

Four recurring mistakes

• Using an ID from project list where a canvas ID is required.
• Assuming upload is enough and skipping asset create.
• Hard-coding a model because it worked in one environment.
• Adding a second build-draft after automatic generation already created the node.

# Wrong: stop after upload
workrally upload ./file.png -o json

# Correct: ingest the returned URL as a project asset
workrally upload ./file.png -o json
workrally asset create --url <cdn_url> --project-id <project_id> -o json

Troubleshooting order

1. Identify whether the operation is for a project, canvas, asset, material or shot.
2. Confirm that every ID came from the matching list or get command.
3. Confirm the URL is a current WorkRally-managed media URL.
4. Only then inspect model, aspect ratio, duration, count and prompt.

When uncertain, run workrally tools describe <tool_name> to inspect the current schema, then compare the request with the relevant focused guide.