Documentation · App Builder
Validation errors and warnings
The App Builder checks a manifest in three layers:
- Schema. Field names, types, enums and patterns, against the manifest's JSON Schema.
- References and rules. What the schema cannot see: names that must point at something that exists, and combinations that would break the app or leak data. These are errors.
- Design checks. Things that work but are probably wrong, such as a collection nobody can fill. These are warnings.
Where you see them:
- App Studio shows errors as you edit. Warnings appear once there are no errors.
- Publish refuses a manifest with errors. Warnings do not block publishing.
- The runtime validates the published manifest again and does not serve an invalid one.
- Export refuses a published manifest with errors, and phone-app settings with problems.
In the messages below, <…> stands for a name from your manifest.
Schema errors
Schema errors have the form <path>: <message>. The path points at the place in the manifest (<root> for the top level); the message is the JSON Schema validator's.
| Example | Meaning | Fix |
|---|---|---|
<root>: must have required property 'spec' | A required field is missing. | Add it. The top level needs apiVersion, kind, metadata, spec; spec needs pattern and agents. |
/spec/agents/0: must have required property 'profile' | The first agent has no profile. | Add profile.ref or profile.inline. |
/spec: must NOT have additional properties | A field the schema does not know (often a typo). | Remove or rename it. |
/apiVersion: must be equal to constant | apiVersion must be webrobot.eu/v1alpha1; kind must be VerticalApp. | Use the exact values. |
/spec/pattern: must be equal to one of the allowed values | A value outside the enum. | Use one of the values listed in the reference. |
/metadata/slug: must match pattern "^[a-z][a-z0-9-]{1,38}[a-z0-9]$" | A name in the wrong format. | Slugs: 3–40 characters, lower case, digits, -. Keys: lower case, digits, _, -, starting with a letter. |
/spec/agents/0/profile: must match exactly one schema in oneOf | profile has both ref and inline, or neither. | Keep exactly one. |
While the schema has errors, the other checks do not run: fix these first.
Errors: views and references
| Message | Meaning | Fix |
|---|---|---|
view <v>: unknown source '<src>' | The view's source names a job, collection or agent that does not exist. | Fix the name, or declare the job, collection or agent. |
view <v>: unknown child view '<c>' | children names a view that does not exist. | Fix the key or add the view. |
view <v>: a block shows unknown view '<w>' | A view block of a page names a missing view, or the page itself. | Name another existing view. |
view <v>: a data block reads unknown job '<j>' | A data block's source: job:<j> names a missing job. | Fix the name or declare the job in data.jobs. |
view <v>: a data block's teaser plan '<p>' is not a plan or pack | preview.unlessPlan of a data block is not a plan or pack key. | Use a key from billing.plans or billing.packs. |
view <v>: preview.unlessPlan '<p>' is not a plan or pack | Same, on the view. | Same. |
view <v>: unknown approval '<a>' | An approvals view lists an approval that does not exist. | Fix the key. |
view <v>: unknown template '<t>' | An instances view names a missing template. | Fix template. |
field <f>: dependsOn unknown field '<g>' | A form field depends on a field that is not in the form. | Fix dependsOn. |
auth.anonymous: unknown agent '<a>' | auth.anonymous.agents names a missing agent. | Fix the key. |
auth.anonymous: unknown view '<v>' | auth.anonymous.views names a missing view. | Fix the key. |
metadata: defaultLang not in langs | The default language is not one of the app's languages. | Add it to langs or change defaultLang. |
branding: theme auto needs paletteDark | A theme that follows the device needs a dark palette. | Add branding.paletteDark, or use another theme. |
Errors: forms and bookings
| Message | Meaning | Fix |
|---|---|---|
view <v>: a form needs collection, a declared collection | A form view without a valid collection. | Set collection to a declared collection. |
view <v>: collection <c> declares no fields to fill | The form's collection has no fields. | Declare the collection's fields. |
view <v>: field '<f>' is not a field of <c> | The view lists a field its collection does not have (forms and bookings). | Fix the name or add the field to the collection. |
view <v>: visitors may only send to the owner's inbox — make <c> ownedBy org | A form open to visitors writes a collection that is not the owner's back office. | Set ownedBy: org on the collection, or remove the form from auth.anonymous.views. |
view <v>: a template instance's records are written by its agent, not by a form | The form writes a collection owned by instance. | Point the form at another collection. |
view <v>: submit.redirect '<r>' is not a view | After sending, the form goes to a missing view. | Fix submit.redirect. |
view <v>: a booking view needs collection, a declared collection | A booking view without a valid collection. | Set it. |
view <v>: bookings are the users' own records — make <c> ownedBy user (staff see them through access rules) | Bookings must belong to the users who make them. | Set ownedBy: user; give staff an access rule. |
view <v>: resources '<r>' is not a collection | resources names a missing collection. | Fix it. |
view <v>: resources must be a collection everyone reads (ownedBy app or shared) | The bookable resources must be visible to everyone. | Set ownedBy: shared or app on that collection. |
view <v>: slots.from must be before slots.to | The booking day ends before it starts. | Swap or fix the times. |
Errors: data and collections
| Message | Meaning | Fix |
|---|---|---|
data.collections: '<c>' is a reserved name (the runtime's own data) | You declared a collection with a name the runtime uses. | Rename it. Reserved: users, login_tokens, mcp_sessions, credit_ledger, runs, approvals, chats, event_log, instances, scheduled_runs, scheduler, memory, meta, sessions, outbox, files, file_blobs, credentials, push_devices, push_log. |
<path>: collection '<c>' is reserved (the runtime's own data) | Something (a source, a tool, a trigger…) points at a reserved collection. | Point it at one of your own collections. |
<path>: unknown collection '<c>' | A collection:<c> reference or a collection key names an undeclared collection. The path says where. | Declare the collection or fix the name. |
collection <c>: access for unknown role '<r>' | An access rule names a role not in auth.roles. | Fix the role or declare it. |
collection <c>: everyone reads it already (ownedBy <o>); an access rule only makes sense with can write | A read-only rule on an app or shared collection does nothing. | Add can: [write], or remove the rule. |
collection <c>: access gives every record to '<r>', the role anyone gets at signup — add a where naming the user, or use an invite/derived role | Anyone who signs up would read every record. | Add a where with {user.email} or {user.id}, or give the rule to an invite or derived role. |
data.credentials: users connect their keys on the account page — add a view of type account | The app asks users for API keys but has no account page. | Add a view with type: account. |
<where>: acrossUsers aggregates a collection of user records (ownedBy user) | A groupBy with acrossUsers reads a collection that is not owned by users. | Use it only on a collection with ownedBy: user. |
<where>: acrossUsers needs minCount of at least 5 (no small group can single out a user) | Groups across users must be big enough to stay anonymous. | Set minCount: 5 or more. |
Errors: agents and tools
| Message | Meaning | Fix |
|---|---|---|
agent <a>: context <k> uses unknown slot '<s>' | A context entry from: slot:<s> names a missing slot. | Fix it or declare the slot in spec.slots. |
agent <a>: optional block {?<x>} is never closed | A {?x} or {!x} block has no {/x}. (The message says {?x} for both.) | Add {/x}. |
agent <a>: goalTemplate placeholder {<x>} is not a form field, a context key or a built-in — … | Nothing fills {x}: the agent would get a goal with a hole. | Use a form field, a built-in, a context entry (from: collection:…, slot:…), or remove it. |
agent <a>: tool <t> uses unknown collection '<c>' | A tool's collection is not declared. | Fix it or declare the collection. |
agent <a>: tool <t> uses unknown slot '<s>' | A call tool's slot is not declared. | Fix it or declare the slot. |
agent <a>: tool <t> reads uploaded files, but no form or collection field has type file | A read_file tool with nothing to read. | Add a file field to the form or a collection, or remove the tool. |
agent <a>: tool <t> is declared by another agent with a different action, target or limits — give one of them another name | Two agents use one tool name for different things. | Rename one, or make them identical (only the description may differ). |
agent <a>: tool <t> (http) declares no http.url | An http tool without a URL. | Add http.url. |
agent <a>: tool <t> calls <host>, which is not in spec.egress.hosts | The tool's host is not allowed. | Add the host to spec.egress.hosts. |
agent <a>: tool <t>: https://{host} is the user's own host, saved with a credential — add http.credential | {host} is filled from the user's credential, so the tool needs one. | Add http.credential. |
agent <a>: tool <t>: https://{host} needs a *.<domain> entry in spec.egress.hosts (e.g. *.myshopify.com) | The user's own host must fall under a wildcard. | Add a *.<domain> entry. |
agent <a>: tool <t>: credential '<p>' is not an api_key credential in spec.data.credentials | The tool sends a key for a provider the app does not declare (as api_key). | Declare it in data.credentials. |
agent <a>: MCP server <n>: a header looks like a literal secret — use ${VAR} | A header of an MCP server holds what looks like a key. | Replace it with ${VAR}, a credential of your organisation. |
agent <a>: delegates: unknown agent '<d>' | delegates names a missing agent. | Fix it. |
agent <a>: delegates to itself | An agent cannot delegate to itself. | Remove it. |
agent <a>: delegation loop through <d> | Agents delegate to each other in a circle. | Break the loop. |
agent <a>: awaits unknown approval '<ap>' | awaits names a missing approval. | Fix it or declare it in spec.approvals. |
agent <a>: memory instance, but no template instantiates it | Per-instance memory needs a template using this agent. | Add a template, or use memory: user. |
Agents visitors use without signing in
| Message | Meaning | Fix |
|---|---|---|
agent <a>: visitors use it without signing in, but tool <t> sends data to an external service (POST) | A visitors' agent with an http tool that is not GET. | Use GET, or remove the agent from auth.anonymous.agents. |
agent <a>: visitors use it without signing in, but tool <t> needs the user's own credential | Visitors have no keys of their own. | Use a credential with scope: org, or require sign-in. |
agent <a>: visitors use it without signing in, but tool <t> reaches '<c>', the owner's private data (ownedBy org) | A visitors' agent could read the back office. | Remove the tool, or require sign-in. |
agent <a>: visitors use it without signing in, but tool <t> writes '<c>', which every user shares (ownedBy <o>) | A visitor could change shared data. | Make the tool read-only, or require sign-in. |
Errors: teams, approvals, templates, channels
| Message | Meaning | Fix |
|---|---|---|
team <t>: an agent has the same key | Team and agent keys share one namespace. | Rename the team. |
team <t>: a sequence needs steps | mode: sequence without steps. | Add steps. |
team <t>: unknown agent '<a>' | A step, lead or member is not an agent. | Fix the key. |
team <t>: an agent appears twice in the steps | Each agent may be one step. | Remove the duplicate. |
team <t>: step <a> runs after '<p>', which is not a step | after names something outside the steps. | Fix after. |
team <t>: the steps form a cycle | The after edges loop. | Remove an edge. |
team <t>: a swarm needs a lead / a swarm needs members | mode: swarm without lead or members. | Add them. |
team <t>: agent <a> must be inline to be part of a team | The team's profile is built from its members' inline definitions. | Give the agent an inline profile. |
approval <k>: unknown role '<r>' | The approver role is not declared. | Fix it or declare it in auth.roles. |
approval <k>: the approver role '<r>' is given at signup — use an admin, invite or derived role, or decidedBy requester when the user confirms their own agent's proposal | Anyone could sign up and approve. Also shown when role is missing (with ''). | Use a staff role, or decidedBy: requester. |
approval <k>: decidedBy requester takes no role (only the requesting user decides) | A role would be ignored. | Remove role. |
approval <k>: no agent awaits it | Nothing can ask for this approval. | Add it to an agent's awaits, or remove it. |
template <k>: needs exactly one of agent, team | A template must name one agent or one team. | Keep exactly one. |
template <k>: unknown agent '<a>' / unknown team '<t>' | The template names something missing. | Fix it. |
template <k>: two params with the same name | Parameter names must be unique. | Rename one. |
template <k>: deliver: unknown role '<r>' | The report goes to an undeclared role. See Recipients. | Fix the role. |
channel <type>: unknown agent '<a>' | A channel names a missing agent. | Fix it. |
Errors: triggers
| Message | Meaning | Fix |
|---|---|---|
trigger <k>: on needs exactly one of cron, collection, webhook, payment, approval, call, date | Zero or several sources. | Keep one source. |
trigger <k>: needs exactly one of start (an agent, team or job), notify (an email), write (save a record) or charge (credits) | Zero or several actions. | Keep one action. |
trigger <k>: start needs exactly one of agent, team, job | start names none or several targets. | Keep one. |
trigger <k>: unknown agent '<a>' / unknown team '<t>' / unknown job '<j>' | The target does not exist. | Fix it. |
trigger <k>: unknown collection '<c>' | on.collection is not declared. | Fix it. |
trigger <k>: on.date reads unknown collection '<c>' | on.date.collection is not declared. | Fix it. |
trigger <k>: unknown approval '<a>' | on.approval is not declared. | Fix it. |
trigger <k>: '<p>' is not a plan or pack | on.payment is not a plan or pack key (or *). | Fix it. |
trigger <k>: op and where apply to a collection | op or where without on.collection (where is also allowed with call and date). | Remove them or add the collection. |
trigger <k>: decision applies to an approval | decision without on.approval. | Remove it. |
trigger <k>: '<c>' is not a phone channel | on.call does not name a phone channel. | Fix it (phone channels are not available yet). |
trigger <k>: callEvent applies to a call | callEvent without on.call. | Remove it. |
trigger <k>: <a> writes <c>, which starts it — add a where filter | The agent writes the collection that starts it: it would start itself on every run. | Add an on.where filter (or use op: update). |
trigger <k>: write to unknown collection '<c>' | write.collection is not declared. | Fix it. |
trigger <k>: write cannot target an instance's collection | Instance records are written by the instance's agent. | Use another collection. |
trigger <k>: writes the collection that starts it | A write into the collection of on.collection would loop. | Use another collection. |
trigger <k>: charge needs an event with a user (a record, an approval, a payment, a date) | A cron or webhook trigger has no user to charge. | Use another source. |
Errors: recipients
These come from triggers[].notify.to, schedules[].deliver.to and templates[].deliver.to. <where> is, for example, trigger <k>: notify.
| Message | Meaning | Fix |
|---|---|---|
<where>: unknown role '<r>' | role:<r> names an undeclared role. | Fix it. |
<where>: 'record.<f>' needs an event with a record (collection, date, approval, call or webhook) | There is no record to read the address from. | Use owner, admins or role:<key>. |
schedule #<i>: deliver needs an agent's report | deliver on a schedule without an agent. | Add the agent or remove deliver. |
schedule #<i>: deliver needs to (admins or role:<key>) — an app-wide schedule has no owner | A schedule has no owner to send to. | Set deliver.to. |
Errors: billing, limits, schedules
| Message | Meaning | Fix |
|---|---|---|
billing: free cannot be combined with other modes | free with another mode. | Keep free alone, or remove it. |
billing: credits mode needs a way to get credits (packs, plans with credits, or signupCredits) | Users could never get credits. | Add packs, plan credits or signupCredits. |
billing: subscription mode needs plans | Nothing to subscribe to. | Add billing.plans. |
billing.costs: unknown agent '<a>' | A cost key agent:<a> names a missing agent. | Fix it. |
billing.costs <k>: perUnit field '<f>' is not a form field | The price follows a field the form does not have. | Fix perUnit.field. |
billing.costs <k>: perUnit field '<f>' must be a number field | Only a number can be multiplied. | Use a number field. |
billing.costs <k>: perUnit is a fixed price per unit — not metered as well | perUnit and metered together. | Keep one. |
limit: unknown agent '<a>' | action: agent:<a> names a missing agent. | Fix it. |
limit: unknown collection '<c>' | action: create:<c> names a missing collection. | Fix it. |
limit <action>: '<p>' is not a plan or pack | A key of plans is not a plan or pack. | Fix it. |
schedule: unknown agent '<a>' / schedule: unknown job '<j>' | The schedule names something missing. | Fix it. |
Warnings
Warnings come from the design checks. A published app keeps working when a new check is added here.
| Message | Meaning | Fix |
|---|---|---|
collection <c>: <readers> read(s) it, but nothing writes it — add a form view on it (the users fill their own records), an agent tool that writes or appends to it, or a trigger write; or, for a list the admins keep, make it ownedBy shared (admins fill it on the data page) | Pages, tools, selects or triggers read users' records that nothing in the app creates: they stay empty. | Add a writer, or change the owner to shared. |
view <v>: a form for everyone cannot add to <c>, a <o> collection only the admins fill — set roles: [admin] (or drop the form: admins have the data page), or own the records by user | A form open to all users writes a catalogue only admins fill. | Set roles: [admin], drop the form, or set ownedBy: user. |
view <v>: roles <r> cannot add to <c>, a <o> collection only the admins fill — keep roles: [admin], or own the records by user | Same, for a form limited to non-admin roles. | Same. |
role <r>: the admins see no page in the menu (every menu page names other roles) — add <r> to the roles of the pages they run, such as the queues, dashboards and approvals | Admins would sign in to an empty menu. | Add the admin role to the pages they use. |
Phone app
When the manifest has spec.mobile, these are shown as warnings in App Studio, and the export of the phone app refuses them ("the phone app settings are not valid").
| Message | Meaning | Fix |
|---|---|---|
mobile.appId '<id>': reverse-DNS, lower case, at least three parts (e.g. eu.webrobot.myapp) | The store identifier is malformed. | Use something like eu.example.myapp. It cannot change once published. |
mobile.capabilities: '<c>' is not an approved capability | Not in the approved list. | Remove it. |
mobile.capabilities: '<c>' twice | Declared twice. | Remove the duplicate. |
mobile.capabilities <c>: a reason is required (the phone shows it when asking the permission) | The phone asks the user for this permission and must say why. | Add reason. |
mobile.capabilities <c>: needs '<d>' too | One capability depends on another (backgroundLocation needs location). | Add it. |
mobile.version '<v>': x.y.z | The version format. | Use 1.2.3. |
mobile.capabilities: '<c>' — no part of the app can use it yet: remove it | contacts, bluetooth, backgroundLocation, localNotifications and speech are not usable yet. | Remove it. |
mobile.capabilities: '<c>' is declared but nothing in the app uses it (the stores refuse unused permissions): remove it | A permission nobody uses. | Remove it, or add what uses it. |
mobile.capabilities: <feature> (<where>) needs '<c>' in the phone app | The app uses a phone feature (a position field, a barcode field, a photo field, an add-to-calendar button, a share button, the app lock) without declaring its capability. | Add the capability. |
Publish errors
Publishing runs the validation again, then creates the app's parts on the platform. An error names the step that failed: <step>: <message>.
| Message | Meaning | Fix |
|---|---|---|
save a draft first | There is no saved draft. | Save, then publish. |
stored draft is not valid JSON | The saved draft cannot be read. | Save the draft again from App Studio. |
validate: <errors> | The draft has validation errors (the first five are listed). | Fix them. |
app tools: <message> | The app's tool endpoint could not be set up. | Try again; contact support if it persists. |
agent <a>: <message> | The platform refused the agent's inline profile. | Read the message: usually the inline definition. |
team <t>: <message> | The platform refused the team's profile. | Same. |
team <t>: agent <a> has no inline crew | A team member's inline profile has no crews. | Give the agent at least one crew. |
pipeline: inline pipeline is not YAML stages or a pipeline spec | A job's inline pipeline cannot be read. | Fix the YAML. |
pipelines: <message> | The platform refused the jobs' pipelines. | Read the message. |
job <j>: manifest applied without this Job | The platform did not create the job. | Publish again; check the pipeline. |
api key: <message> / credential: <message> | The app's API key could not be created (first publish only). | Check your role in the organisation; try again. |
validate published: <errors> | The manifest after publishing is not valid. | Report it: this should not happen. |
invalid slug | The slug does not match the format. | 3–40 characters, lower case, digits, -. |
slug already taken | Another organisation's app has this slug. | Choose another slug. |
metadata.slug must be <slug> | The manifest's slug differs from the app's. | Keep the slug the app was created with. |
kind must be VerticalApp / apiVersion must be webrobot.eu/v1alpha1 | The envelope is wrong. | Use the exact values. |
host <h> is already used by another app | spec.host or a domain belongs to another app. | Remove it, or free it in the other app first. |
the caller has no organization | Your user has no organisation. | Join or create one. |