Troubleshooting decisions with a model

Two places to look

• The decision — the decision output of the step, a madoo.decision/v1 document — says for each question what was answered, the probability of every option, the threshold and the status. Read it first: almost every “wrong” result is explained there.
• The trace (GET /api/v1/executions/{id}/trace) says whether the step and the steps after it completed, were skipped (and why) or failed (and with which code).

Refused when the workflow is validated

Code	Cause	Fix
missing_dynamic_mapping	the step has no questions	write at least one question
missing_decision_content	nothing is connected to judge: no content (connected or written on the step), no picture, no image set	connect at least one
invalid_on_uncertain, invalid_image_detail, invalid_image_set_limit	a value that is not one of the options	mark / skip_branch / fail; low / high; even / first / fail
invalid_dynamic_config	the questions are not a madoo.decision-questions/v1 object, an unknown field is present, options on a yes/no or a score, levels on a choice, a description over 500 characters, instructions over 2,000	follow the schema; the path points at the field
invalid_question_count	fewer than 1 or more than 16 questions	split into two steps
missing_question_name, invalid_port_name	a question without a name, or a name that is not lowercase letters, digits and _ starting with a letter, at most 40	rename it — the name becomes the port
reserved_port_name	the name is a port of the step (decision, all_accepted, content, images, image_set) or ends in _probability or _level	choose another name
duplicate_dynamic_port	two questions with the same name	give each its own
invalid_question_type	the type is not yes_no, choice or score
missing_question_instructions	empty instructions	write what the model judges
invalid_threshold	the threshold is not a number from 0 to 1, or below 0.5 for a yes/no
missing_question_options, invalid_option, duplicate_option, invalid_option_count	a choice without options, an empty or long value, a value twice, fewer than 2 or more than 50 options
missing_question_levels, invalid_level, duplicate_level, invalid_level_count	a score without levels, an empty or long label, a label twice, fewer than 2 or more than 10 levels
a connection from a port that does not exist	a question was renamed or removed, or its type changed	connect from the new port; the names are on the node and in get_node_type

Every code comes with the path of the field, such as $.nodes[1].parameters.questions.questions[0].name.

The step fails

Code	Cause	Fix
MISSING_INPUT	nothing to judge at run time — the connected content or pictures came empty	check the step that feeds it
INVALID_DECISION_QUESTIONS	the stored questions are not valid (a definition written outside the API)	open the step and fix the question named in the message
DECISION_UNCERTAIN	On Uncertain is fail and an answer is not accepted: the message names each one — “route (uncertain, probability 0.55, threshold 0.70)”	see Thresholds and uncertainty; the model call is charged
TOO_MANY_IMAGES	more than 20 pictures and Image Set Limit fail	even or first, or fewer pictures
IMAGE_SET_FORBIDDEN, IMAGE_SET_INVALID	the image set names a picture of another workspace, an external link, or is not a madoo.image-set/v1	only storage pictures of the workspace
DECISION_INVALID_RESPONSE, DECISION_NO_ANSWERS	the provider answered something unreadable	run again; if it repeats, report it
a provider error with the provider’s message	the provider refused the request — rare, the step validates the limits first	read the message; it is not charged

An answer is uncertain

The probability did not reach the threshold. Look at the probabilities in the decision:

• Two options share the probability (refund 0.55, replacement 0.40) — the content fits both, or the options overlap: describe the boundary, or merge them. Two equally good pictures are a real tie.
• A yes/no near 0.5 — the content does not say: “The customer will send the item back” of a hesitant message came back 0.50. That is the right answer; route it to a person.
• Everything is a little below the threshold — the threshold may be too high for this question: set it on your examples (how).
• A score — subjective scales are the least sure kind; sort by the continuous value instead of requiring a level.

A port has no value

The port is	Because
absent, and the steps after it skipped (branch_rejected)	On Uncertain is skip_branch and that answer was not accepted	by design
absent; a step that needs it is skipped (upstream_absent), the others run	the answer was refused or invalid with mark	see the decision’s status
absent, with every answer of the step	the step failed or was skipped — see the trace

The answer is wrong

1. Read the question as the model does — literally. “Delivered later than promised” is not “late”: see Writing questions.
2. Is the right answer among the options? Add other, or the missing option.
3. Is the fact in the content? The model judges only what it is given — put the brief, the facts, the policy in it.
4. Is it a number, a count or a date? Compute it with Calculate and compare it with Predicate.
5. Is it a small detail in a picture? Try high image detail, or Image Analysis.
6. Was it accepted with a high probability? Then the question, not the threshold, needs work.

Costs higher than expected

A step that receives many pictures at high detail reads up to about 2,600 tokens a picture: use low for whole-photo checks. Asking each question in its own step reads the content and the pictures again each time: ask them together. The estimate before a run assumes one picture and, when the content comes from an upstream step, 1,000 tokens — see Costs, speed and limits.