vxcontrol/pentagi · error

failed to unmarshal %s store guide action arguments: %w

Error message

failed to unmarshal %s store guide action arguments: %w

What it means

Returned by the guide tool dispatcher (backend/pkg/tools/guide.go) when the JSON arguments of the 'store' guide action cannot be unmarshaled into StoreGuideAction (expects 'question' and 'guide' string fields). Indicates malformed tool-call arguments from the LLM; the call is rejected before storing anything.

Source

Thrown at backend/pkg/tools/guide.go:220

				ctx,
				agentCtx.ParentAgentType,
				agentCtx.CurrentAgentType,
				filtersData,
				queriesText,
				database.VecstoreActionTypeRetrieve,
				buffer.String(),
				g.taskID,
				g.subtaskID,
			)
		}

		return buffer.String(), nil

	case StoreGuideToolName:
		var action StoreGuideAction
		if err := json.Unmarshal(args, &action); err != nil {
			logger.WithError(err).Error("failed to unmarshal store guide action")
			return "", fmt.Errorf("failed to unmarshal %s store guide action arguments: %w", name, err)
		}

		guide := fmt.Sprintf("Question:\n%s\n\nGuide:\n%s", action.Question, action.Guide)

		// Anonymize before anything else so all downstream paths (including error
		// branches that emit langfuse events) only ever expose the anonymized form.
		var (
			anonymizedGuide     = g.replacer.ReplaceString(guide)
			anonymizedQuestion  = g.replacer.ReplaceString(action.Question)
			anonymizedGuideOnly = g.replacer.ReplaceString(action.Guide) // used in slow-path embedding text
		)

		eventMetadata := map[string]any{
			"tool_name":  name,
			"message":    action.Message,
			"doc_type":   guideVectorStoreDefaultType,
			"guide_type": action.Type,
		}

View on GitHub (pinned to ea665308ba)

Solutions

1. Check the logged 'args' field for the exact malformed payload.
2. Retry the agent turn; unescaped quotes from the model are usually transient.
3. Verify the tool schema for store_guide (question, guide fields) matches what the prompt instructs.
4. Pre-sanitize/strip markdown fences before Unmarshal.
5. Enable strict/JSON-mode function calling on the provider.

func isValidStoreGuideArgs(args json.RawMessage) bool {
    var probe struct {
        Question string `json:"question"`
        Guide    string `json:"guide"`
    }
    return json.Unmarshal(args, &probe) == nil && probe.Guide != ""
}

func asStoreGuideAction(args json.RawMessage) (*StoreGuideAction, bool) {
    var a StoreGuideAction
    if err := json.Unmarshal(args, &a); err != nil || a.Question == "" {
        return nil, false
    }
    return &a, true
}

out, err := tool.Handle(ctx, "store_guide", args)
if err != nil {
    if strings.Contains(err.Error(), "failed to unmarshal") {
        return regenerateToolCallWithSchemaExample()
    }
    return err
}

When it happens

Trigger: Agent emits invalid JSON for store_guide: malformed question/guide strings with unescaped quotes/newlines, missing required fields, or completely non-JSON args.

Common situations: LLM writes the guide content containing raw quotes or control characters without proper JSON escaping; oversized or truncated tool-call output; strict-mode providers disabled so the model free-forms arguments.

Related errors

• failed to unmarshal search arguments: %w
• failed to unmarshal %s search guide action arguments: %w
• failed to unmarshal primary agent msg chain %d: %w
• failed to parse patch_flow_subtasks args: %w
• invalid subtask patch: %w

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/116c1b77b801d1bd. Report an issue: GitHub.