Agent editor errors and warnings

Status: Current | Last reviewed: 2026-10-05

The editor presents each issue with a short label and next step. View details expands its diagnostic and location. Severity and publishing/preview gates remain owned by the original validator; presentation does not change them.

Scope and sources

This inventory covers the agent editor notification bell, including full-screen Preview, and the readiness reason on disabled preview controls. It is a catalog of diagnostic families, not a finite list of provider error strings. Provider libraries, schema fields, tenant capability definitions, and API failures can produce new text; every runtime gate and unknown diagnostic has a fallback. Workflow-editor validation and unrelated application screens retain their own UI.

Source	Issues
lib/schema.ts, lib/validate.ts	Configuration shape, missing settings, duplicate stages, inline actions, silent or overlapping voices
lib/validate-node-capabilities.ts	Capability ownership, scope, dependencies and supported stages; authentication methods and code settings; payment methods, capture, limits and refunds; secure capture fields
lib/agent-logic-validation.ts, lib/procedure-schema.ts	Variable definitions and writes, expressions, conditions, action bindings/captures, response guards, subagents, guided steps, procedures and provider limitations
lib/agent-config-validation.ts and publish validators	Tenant transfer policy, consult routing, translation references, data-tool wiring, tenant capability policy and publishing failures
ai-orchestrator lib/pipecat/pipeline/preflight.py	The ten runtime gates listed below; provider-specific configuration and connection resolution
Agent page, use-agent-versioning.ts	Load, save, publish, export, delete, selection, JSON and chat-start failures
PhoneCallTest, TesterSidebarPanel, AutosaveIndicator	Phone permissions/connection, real-SMS number, recording, typed speech, Debug, autosave permissions and connection failures

Agent Logic and tenant checks run at their existing call sites. Cataloguing them does not add new client validation or change publishing policy. Server diagnostic aggregates retain their source context in details; client validation arrays become one notification per issue. Presentation preserves warning severity. Nova now refreshes changed instructions at a safe turn boundary, so its validators no longer emit the six-minute conditional/prompt-program advisories. Their catalog entries remain for compatibility with diagnostics from older runtimes.

Readiness checks use the exact :draft or :vN version open in the editor. The preflight API tenant-checks the parent agent, then forwards the full version identifier. allow_draft authorizes draft access; it does not select the draft. Bare IDs retain the runtime resolver's current-publication-first behavior. Changing versions clears the previous readiness result and triggers a new check.

Presentation contract

• lib/editor-issues.ts is the client-safe catalog. Structured code takes priority; legacy messages use ordered matchers, then gate-specific copy.
• EditorNotificationsProvider applies this presentation to page notices, nested Preview/autosave notices and editor action messages. Short, already readable diagnostics need no redundant disclosure. Info/success messages keep their existing presentation.
• Details preserve the check, stage/path, service, flow and runtime option when supplied. Notifications with the same label but different locations remain separate. Repeated identical issues are deduplicated.
• Configuration values are not copied from validation objects. Legacy schema dumps are replaced before message matching; tokens, common credentials and service URLs are redacted. Oversized diagnostics become a bounded explanation.
• Runtime schema_diagnostics.py emits code, path and a concise message. It selects union branches matching the stage's type discriminator before comparing failures, so a service stage does not inherit a swimlane group's missing-field warning. It includes up to five failing setting paths/checks without serializing rejected instances. These fields are additive; the original warning count and gate are preserved.
• View details uses native keyboard-accessible disclosure. Blocking text remains visible before expansion. No truncation hides an issue's meaning.

Friendly labels (92 families)

Code	Friendly label	Guidance
configuration-schema	Configuration needs review	A setting does not match the expected format. Review the affected stage’s settings.
readiness-unavailable	Readiness check unavailable	Try again shortly. If this continues, ask an administrator to check the agent runtime.
conditional-prompt-session-refresh	Conditional prompt updates may be delayed	Nova Sonic uses updated conditions at its next automatic session refresh, around every six minutes. A condition change does not trigger an immediate restart.
conditional-prompt-start-only	Conditional prompts only update at call start	Changes during the call will not update these instructions. For live updates, use text output with a separate Text-to-Speech stage.
prompt-actions-rotation	Prompt actions repeat when the voice session renews	These actions run at call start and when Nova Sonic renews the session, about every six minutes. They do not run on every turn.
prompt-actions-start-only	Prompt actions only run at call start	For actions that run on every turn, use text output with a separate Text-to-Speech stage.
voice-guard-limited	Response checks have limited voice control	This voice provider checks the transcript. Use text output with a separate Text-to-Speech stage to check every response before it is spoken.
parallel-logic	Rules cannot run in this parallel branch	Move the rules to a stage in a sequential pipeline so they can receive and check each message.
overlapping-voices	More than one voice may speak	Check which stages produce audio. Turn off extra voice outputs unless overlapping voices are intentional.
silent-agent	The agent has no voice output	Enable voice output on this stage or add a Text-to-Speech stage after it.
duplicate-stage	Two stages share the same identifier	Give each stage a unique identifier, or remove the duplicate stage.
inline-tool-missing	An inline action is not connected	Select the inline action again, add its definition, or remove the unused reference.
inline-tool-duplicate	Two inline actions share an identifier	Give each inline action on this stage a unique identifier.
inline-tool-invalid	An inline action needs setup	Open the action and check its name, identifier, and definition.
tool-references-invalid	The action list needs updating	Choose actions from the tool picker. Keep inline action definitions in the inline action editor.
auth-no-method	Choose a verification method	Open Customer Authentication and select a method callers can use to verify their identity.
auth-assurance	Verification methods do not meet the required level	Review the required assurance level and selected methods in Customer Authentication.
auth-sms-only	Verification relies on text messages	Consider offering passkeys as an additional verification method.
auth-knowledge-tools	Knowledge checks need matching actions	Select and attach enough verification actions to satisfy the required number of checks.
auth-code-expiry	Verification codes stay valid too long	Set code expiry to ten minutes or less in Customer Authentication.
auth-code-length	Verification codes are too short	Use codes with at least six digits.
auth-code-attempts	Verification allows many guesses	Lower the allowed attempts in Customer Authentication.
payment-method	Choose a supported payment method	Open Payments and select at least one available payment method.
payment-entry	Choose how callers enter payment details	Enable the phone keypad, the on-screen payment form, or both.
payment-chat-keypad	Phone keypad entry is unavailable in chat	Use the on-screen payment form for this chat stage.
payment-form	The payment form needs Multimodal UI	Enable Multimodal UI on a stage so callers can open the payment form.
payment-amount	Payment limits need whole amounts	Enter a non-negative whole number in the currency’s smallest unit, such as cents.
payment-currency	Choose a valid currency	Use a supported three-letter currency code, such as USD or GBP.
payment-timeout	Adjust the payment entry timeout	Allow between 5 and 120 seconds for each keypad entry.
payment-retries	Adjust payment retries	Allow between zero and five retries per payment entry.
payment-return-key	Choose one key to return to the agent	Use a single digit, star, or hash as the return key.
payment-confirmation	Callers cannot confirm card details before charging	Enable confirmation in Payments to let callers check their entry before a charge.
payment-refunds	Refunds can include earlier conversations	Review whether refunds should be limited to payments from the current conversation.
payment-parallel	Payments need a sequential pipeline	Move payment collection to a pipeline without parallel branches.
secure-field-label	A secure field needs a label	Add a spoken label or choose a built-in field type so the agent can collect it.
secure-fields-empty	Secure Data Capture has no fields to collect	Add at least one field before using this capability.
capability-duplicate	A capability is enabled on more than one stage	Keep this capability enabled on one supported stage.
capability-stage	This stage does not support the capability	Move the capability to a supported conversation stage.
capability-missing	A capability is no longer available	Select an available capability or remove the old reference.
capability-builtin	Enable this capability from its card	Use Add capability to enable the built-in capability.
capability-scope	The capability definition needs updating	Ask the capability owner to review its supported scope and runtime settings.
capability-dependency	A required capability is missing	Enable the required capability on the same stage.
variable-read	A variable may not have a value yet	Declare the variable and check that an action or caller response sets it before it is used.
variable-write	A captured variable needs a definition	Declare it in Variables to add a type, description, and optional default.
variable-readonly	A linked variable cannot be changed here	Capture the result into a writable variable, or update the linked source.
variable-description	A variable needs a description	Describe what the variable holds so authors and the agent know how to use it.
variable-invalid	A variable needs updating	Review its name, type, source, and default value in Variables.
subagent-return-unused	This return condition is not used	Remove the condition or choose a subagent mode that supports conditional return.
guided-script-unused	This guided script is not being used	Switch the subagent to Guided to run its steps, or remove the unused script.
guided-capture-missing	A reply will not be saved	Choose a variable for this guided step if later steps need the caller’s answer.
guided-sensitive-capture	This step may collect sensitive information	Use Payments or Secure Data Capture for payment and identity details.
guided-form-disabled	This step’s form is unavailable	Enable Multimodal UI or choose another input method for the step.
guided-stt	Guided flows need speech recognition	Configure a speech recognition service for guided steps.
guided-tts	Guided flows need a voice	Configure a Text-to-Speech service for guided prompts.
guided-matcher	Guided flows need a matching model	Choose a model for guided reply matching in auxiliary services.
guided-pause	The voice model stays active during guided flows	This provider cannot pause fully. Guided flows still work, but voice-model usage continues.
guided-parallel	Guided flows need a sequential pipeline	Move guided subagents to a pipeline without parallel branches.
guided-steps	A guided step needs updating	Check the step list, answer choices, and branch destinations in the guided subagent.
procedure-model	Procedure checks need a model	Choose a Logic checker model in auxiliary services so judged steps can be checked.
procedure-hidden	Procedure steps are missing from the prompt	Review the procedure settings. Restore the step blocks or clear unused hidden steps.
procedure-empty	The procedure has no steps	Add steps to the prompt when you are ready to use this procedure.
procedure-invalid	A procedure needs updating	Check its step names, dependencies, completion conditions, and monitoring settings.
expression-invalid	A condition cannot be read	Open the condition editor and correct the expression.
prompt-invalid	A prompt instruction needs fixing	Review the highlighted condition or action in the prompt editor.
tool-logic-invalid	An action’s rules need updating	Check its availability condition, input bindings, and result variables.
response-guard-invalid	A response check needs updating	Review its condition and what should happen when a response fails the check.
logic-rule-invalid	A behavior rule needs updating	Review the rule’s trigger, condition, and actions in Behavior.
component-mapping	A screen component’s mapping needs updating	Check the component’s input values and the variables used to save answers.
subagent-invalid	A subagent needs updating	Review its name, routing conditions, and return behavior.
data-tool-wiring	A screen action is not connected	Attach the catalog’s tool connection and enable the action in its operation filter.
transfer-policy	The transfer is not allowed by current settings	Choose an allowed destination or ask an administrator to review the tenant’s transfer settings.
transfer-config	Transfer settings need updating	Review the transfer destination, routing settings, and any translation agent.
save-permission	Saving needs access	Keep this page open and ask an administrator to restore permission to save your changes.
save-failed	Changes could not be saved	Keep this page open and retry saving.
session-expired	Sign in again to continue	Your session has ended. Sign in again before continuing.
agent-not-selected	Choose an agent first	Open an agent before saving, exporting, or starting preview.
invalid-json	The configuration text cannot be read	Check the JSON editor for missing commas, quotes, or brackets.
validation-failed	Some settings need fixing	Review the individual issues in Notifications before saving.
publish-failed	The agent could not be published	Review the current issues, then try publishing again.
export-failed	The agent could not be exported	Check the details for features the selected export format does not support.
delete-failed	The agent could not be deleted	Refresh the agent list and try again.
load-failed	The agent could not be loaded	Refresh the page. If the issue continues, check that the agent is still available to you.
preview-permission	Voice preview needs access	Ask an administrator for permission to use voice preview.
preview-connecting	Voice preview is connecting	Wait for the phone connection, then try starting the call again.
preview-sms-number	Enter a caller number for text messages	Set the caller number in Preview’s template variables before using real SMS.
preview-recording-cleanup-stopped	Recording stopped	Caller audio cleanup stopped working. You can download the portion already recorded. Your call continues.
preview-recording-cleanup-start	Recording could not start	Caller audio cleanup is unavailable. Retry recording in a supported browser.
preview-recording	Preview recording could not finish	Check browser recording permission, then try again.
preview-speech-input	Typed speech is unavailable	Check that the preview call is still connected, then try again.
preview-chat	Chat preview could not start	Try starting a new chat preview.
preview-debug	Debug mode could not be updated	Try changing the Debug setting again.
preview-failed	Preview could not connect	Try starting preview again. If this continues, check your connection and voice service settings.

Runtime gate fallbacks

Gate	Friendly label	Guidance
structural	Configuration needs review	A setting does not match the expected format. Review the affected stage’s settings.
service_mapping	The selected service is unavailable	Check the stage’s provider and service selection.
service_config	A service needs configuration	Open the stage’s Properties and check the required service settings.
credential	A service connection needs attention	Check the selected integration and ask an administrator to confirm its credentials.
tool_ref	An action is unavailable	Select an available action or remove its unused reference.
card_ref	A display card is unavailable	Select an available card in the Copilot settings.
logic	Agent behavior needs review	Review the affected condition, action, or response check in Behavior.
guided	A guided flow needs attention	Review the guided subagent’s steps and auxiliary services.
procedure	A procedure needs attention	Review the procedure’s steps and Logic checker settings.
compliance	A runtime option is restricted	Review the available runtime options with your tenant administrator.

Unknown technical errors use Something needs attention; unknown warnings use Review this agent setting, with a bounded diagnostic behind View details. These fallbacks preserve evidence without presenting an unreviewed provider exception as a user instruction.

Adding an issue

Keep severity and blocking decisions in the producer. Add specific title and guidance to the catalog, prefer a stable code on new structured producers, and add a regression case using the producer's actual diagnostic. Never match against a serialized configuration instance. For a new runtime gate, add fallback copy too; the test compares the catalog with the Python gate declarations.

Regenerate this inventory after editing copy:

cd apps/ai-manager
npx tsx scripts/generate-editor-issue-catalog.ts
npx tsx scripts/generate-editor-issue-catalog.ts --check
node --import tsx --test lib/editor-issues.test.ts

User instructions: Agent editor notifications.