WebRobot
App Builder · pagine

Documentazione · App Builder

Errori e avvisi di validazione

L’App Builder controlla un manifest su tre livelli:

  1. Schema. Nomi dei campi, tipi, enum e formati, rispetto al JSON Schema del manifest.
  2. Riferimenti e regole. Quello che lo schema non vede: nomi che devono puntare a qualcosa che esiste, e combinazioni che romperebbero l’app o esporrebbero dati. Questi sono errori.
  3. Controlli di progettazione. Cose che funzionano ma probabilmente sono sbagliate, come una raccolta che nessuno può riempire. Questi sono avvisi.

Dove li vedi:

  • App Studio mostra gli errori mentre modifichi. Gli avvisi compaiono quando non ci sono più errori.
  • Publish (pubblica) rifiuta un manifest con errori. Gli avvisi non bloccano la pubblicazione.
  • Il runtime valida di nuovo il manifest pubblicato e non serve un manifest non valido.
  • L’esportazione rifiuta un manifest pubblicato con errori, e impostazioni dell’app per telefono con problemi.

Nei messaggi qui sotto, <…> sta per un nome del tuo manifest.

Errori di schema

Gli errori di schema hanno la forma <path>: <message>. Il percorso indica il punto del manifest (<root> per il livello più alto); il messaggio è quello del validatore JSON Schema.

EsempioSignificatoCorrezione
<root>: must have required property 'spec'Manca un campo obbligatorio.Aggiungilo. Il livello più alto richiede apiVersion, kind, metadata, spec; spec richiede pattern e agents.
/spec/agents/0: must have required property 'profile'Il primo agente non ha profile.Aggiungi profile.ref o profile.inline.
/spec: must NOT have additional propertiesUn campo che lo schema non conosce (spesso un errore di battitura).Rimuovilo o rinominalo.
/apiVersion: must be equal to constantapiVersion deve essere webrobot.eu/v1alpha1; kind deve essere VerticalApp.Usa i valori esatti.
/spec/pattern: must be equal to one of the allowed valuesUn valore fuori dall’enum.Usa uno dei valori elencati nel riferimento.
/metadata/slug: must match pattern "^[a-z][a-z0-9-]{1,38}[a-z0-9]$"Un nome nel formato sbagliato.Slug: 3–40 caratteri, lettere minuscole, cifre, -. Chiavi: lettere minuscole, cifre, _, -, iniziando con una lettera.
/spec/agents/0/profile: must match exactly one schema in oneOfprofile ha sia ref sia inline, o nessuno dei due.Tienine esattamente uno.

Finché lo schema ha errori, gli altri controlli non vengono eseguiti: correggi prima questi.

Errori: viste e riferimenti

MessaggioSignificatoCorrezione
view <v>: unknown source '<src>'Il source della vista nomina un job, una raccolta o un agente che non esiste.Correggi il nome, o dichiara il job, la raccolta o l’agente.
view <v>: unknown child view '<c>'children nomina una vista che non esiste.Correggi la chiave o aggiungi la vista.
view <v>: a block shows unknown view '<w>'Un blocco view di una pagina nomina una vista mancante, o la pagina stessa.Nomina un’altra vista esistente.
view <v>: a data block reads unknown job '<j>'Il source: job:<j> di un blocco dati nomina un job mancante.Correggi il nome o dichiara il job in data.jobs.
view <v>: a data block's teaser plan '<p>' is not a plan or packpreview.unlessPlan di un blocco dati non è la chiave di un piano o di un pacchetto.Usa una chiave di billing.plans o billing.packs.
view <v>: preview.unlessPlan '<p>' is not a plan or packLo stesso, sulla vista.Lo stesso.
view <v>: unknown approval '<a>'Una vista approvals elenca un’approvazione che non esiste.Correggi la chiave.
view <v>: unknown template '<t>'Una vista instances nomina un modello mancante.Correggi template.
field <f>: dependsOn unknown field '<g>'Un campo del modulo dipende da un campo che non è nel modulo.Correggi dependsOn.
auth.anonymous: unknown agent '<a>'auth.anonymous.agents nomina un agente mancante.Correggi la chiave.
auth.anonymous: unknown view '<v>'auth.anonymous.views nomina una vista mancante.Correggi la chiave.
metadata: defaultLang not in langsLa lingua predefinita non è tra le lingue dell’app.Aggiungila a langs o cambia defaultLang.
branding: theme auto needs paletteDarkUn tema che segue il dispositivo richiede una palette scura.Aggiungi branding.paletteDark, o usa un altro tema.

Errori: moduli e prenotazioni

MessaggioSignificatoCorrezione
view <v>: a form needs collection, a declared collectionUna vista form senza una collection valida.Imposta collection su una raccolta dichiarata.
view <v>: collection <c> declares no fields to fillLa raccolta del modulo non ha fields.Dichiara i campi della raccolta.
view <v>: field '<f>' is not a field of <c>La vista elenca un campo che la sua raccolta non ha (moduli e prenotazioni).Correggi il nome o aggiungi il campo alla raccolta.
view <v>: visitors may only send to the owner's inbox — make <c> ownedBy orgUn modulo aperto ai visitatori scrive in una raccolta che non è il back office del proprietario.Imposta ownedBy: org sulla raccolta, o togli il modulo da auth.anonymous.views.
view <v>: a template instance's records are written by its agent, not by a formIl modulo scrive in una raccolta posseduta da instance.Punta il modulo su un’altra raccolta.
view <v>: submit.redirect '<r>' is not a viewDopo l’invio, il modulo va a una vista mancante.Correggi submit.redirect.
view <v>: a booking view needs collection, a declared collectionUna vista booking senza una collection valida.Impostala.
view <v>: bookings are the users' own records — make <c> ownedBy user (staff see them through access rules)Le prenotazioni devono appartenere agli utenti che le fanno.Imposta ownedBy: user; dai al personale una regola di accesso.
view <v>: resources '<r>' is not a collectionresources nomina una raccolta mancante.Correggilo.
view <v>: resources must be a collection everyone reads (ownedBy app or shared)Le risorse prenotabili devono essere visibili a tutti.Imposta ownedBy: shared o app su quella raccolta.
view <v>: slots.from must be before slots.toLa giornata di prenotazione finisce prima di iniziare.Inverti o correggi gli orari.

Errori: dati e raccolte

MessaggioSignificatoCorrezione
data.collections: '<c>' is a reserved name (the runtime's own data)Hai dichiarato una raccolta con un nome che il runtime usa.Rinominala. Riservati: 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)Qualcosa (una sorgente, uno strumento, un trigger…) punta a una raccolta riservata.Puntalo su una delle tue raccolte.
<path>: unknown collection '<c>'Un riferimento collection:<c> o una chiave collection nomina una raccolta non dichiarata. Il percorso dice dove.Dichiara la raccolta o correggi il nome.
collection <c>: access for unknown role '<r>'Una regola di accesso nomina un ruolo che non è in auth.roles.Correggi il ruolo o dichiaralo.
collection <c>: everyone reads it already (ownedBy <o>); an access rule only makes sense with can writeUna regola di sola lettura su una raccolta app o shared non fa nulla.Aggiungi can: [write], o rimuovi la regola.
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 roleChiunque si registri leggerebbe tutti i record.Aggiungi un where con {user.email} o {user.id}, o assegna la regola a un ruolo su invito o derivato.
data.credentials: users connect their keys on the account page — add a view of type accountL’app chiede agli utenti delle chiavi API ma non ha una pagina account.Aggiungi una vista con type: account.
<where>: acrossUsers aggregates a collection of user records (ownedBy user)Un groupBy con acrossUsers legge una raccolta che non è posseduta dagli utenti.Usalo solo su una raccolta con ownedBy: user.
<where>: acrossUsers needs minCount of at least 5 (no small group can single out a user)I gruppi tra utenti devono essere abbastanza grandi da restare anonimi.Imposta minCount: 5 o più.

Errori: agenti e strumenti

MessaggioSignificatoCorrezione
agent <a>: context <k> uses unknown slot '<s>'Una voce di contesto from: slot:<s> nomina uno slot mancante.Correggila o dichiara lo slot in spec.slots.
agent <a>: optional block {?<x>} is never closedUn blocco {?x} o {!x} non ha {/x}. (Il messaggio dice {?x} in entrambi i casi.)Aggiungi {/x}.
agent <a>: goalTemplate placeholder {<x>} is not a form field, a context key or a built-in — …Niente riempie {x}: l’agente riceverebbe un obiettivo con un buco.Usa un campo del modulo, un valore predefinito, una voce di contesto (from: collection:…, slot:…), o rimuovilo.
agent <a>: tool <t> uses unknown collection '<c>'La collection di uno strumento non è dichiarata.Correggila o dichiara la raccolta.
agent <a>: tool <t> uses unknown slot '<s>'Lo slot di uno strumento call non è dichiarato.Correggilo o dichiara lo slot.
agent <a>: tool <t> reads uploaded files, but no form or collection field has type fileUno strumento read_file senza niente da leggere.Aggiungi un campo file al modulo o a una raccolta, o rimuovi lo strumento.
agent <a>: tool <t> is declared by another agent with a different action, target or limits — give one of them another nameDue agenti usano lo stesso nome di strumento per cose diverse.Rinominane uno, o rendili identici (solo la descrizione può differire).
agent <a>: tool <t> (http) declares no http.urlUno strumento http senza URL.Aggiungi http.url.
agent <a>: tool <t> calls <host>, which is not in spec.egress.hostsL’host dello strumento non è consentito.Aggiungi l’host a spec.egress.hosts.
agent <a>: tool <t>: https://{host} is the user's own host, saved with a credential — add http.credential{host} viene preso dalla credenziale dell’utente, quindi lo strumento ne richiede una.Aggiungi http.credential.
agent <a>: tool <t>: https://{host} needs a *.<domain> entry in spec.egress.hosts (e.g. *.myshopify.com)L’host dell’utente deve ricadere sotto un carattere jolly.Aggiungi una voce *.<domain>.
agent <a>: tool <t>: credential '<p>' is not an api_key credential in spec.data.credentialsLo strumento invia una chiave per un provider che l’app non dichiara (come api_key).Dichiaralo in data.credentials.
agent <a>: MCP server <n>: a header looks like a literal secret — use ${VAR}Un header di un server MCP contiene qualcosa che sembra una chiave.Sostituiscilo con ${VAR}, una credenziale della tua organizzazione.
agent <a>: delegates: unknown agent '<d>'delegates nomina un agente mancante.Correggilo.
agent <a>: delegates to itselfUn agente non può delegare a sé stesso.Rimuovilo.
agent <a>: delegation loop through <d>Gli agenti si delegano a vicenda in cerchio.Interrompi il ciclo.
agent <a>: awaits unknown approval '<ap>'awaits nomina un’approvazione mancante.Correggila o dichiarala in spec.approvals.
agent <a>: memory instance, but no template instantiates itLa memoria per istanza richiede un modello che usi questo agente.Aggiungi un modello, o usa memory: user.

Agenti usati dai visitatori senza accesso

MessaggioSignificatoCorrezione
agent <a>: visitors use it without signing in, but tool <t> sends data to an external service (POST)Un agente per visitatori con uno strumento http che non è GET.Usa GET, o togli l’agente da auth.anonymous.agents.
agent <a>: visitors use it without signing in, but tool <t> needs the user's own credentialI visitatori non hanno chiavi proprie.Usa una credenziale con scope: org, o richiedi l’accesso.
agent <a>: visitors use it without signing in, but tool <t> reaches '<c>', the owner's private data (ownedBy org)Un agente per visitatori potrebbe leggere il back office.Rimuovi lo strumento, o richiedi l’accesso.
agent <a>: visitors use it without signing in, but tool <t> writes '<c>', which every user shares (ownedBy <o>)Un visitatore potrebbe modificare dati condivisi.Rendi lo strumento di sola lettura, o richiedi l’accesso.

Errori: squadre, approvazioni, modelli, canali

MessaggioSignificatoCorrezione
team <t>: an agent has the same keyLe chiavi delle squadre e degli agenti condividono un unico spazio dei nomi.Rinomina la squadra.
team <t>: a sequence needs stepsmode: sequence senza passi.Aggiungi steps.
team <t>: unknown agent '<a>'Un passo, un lead o un membro non è un agente.Correggi la chiave.
team <t>: an agent appears twice in the stepsOgni agente può essere un solo passo.Rimuovi il duplicato.
team <t>: step <a> runs after '<p>', which is not a stepafter nomina qualcosa fuori dai passi.Correggi after.
team <t>: the steps form a cycleGli archi after formano un ciclo.Rimuovi un arco.
team <t>: a swarm needs a lead / a swarm needs membersmode: swarm senza lead o members.Aggiungili.
team <t>: agent <a> must be inline to be part of a teamIl profilo della squadra è costruito dalle definizioni inline dei suoi membri.Dai all’agente un profilo inline.
approval <k>: unknown role '<r>'Il ruolo che approva non è dichiarato.Correggilo o dichiaralo 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 proposalChiunque potrebbe registrarsi e approvare. Compare anche quando manca role (con '').Usa un ruolo del personale, o decidedBy: requester.
approval <k>: decidedBy requester takes no role (only the requesting user decides)Un ruolo verrebbe ignorato.Rimuovi role.
approval <k>: no agent awaits itNiente può chiedere questa approvazione.Aggiungila agli awaits di un agente, o rimuovila.
template <k>: needs exactly one of agent, teamUn modello deve nominare un agente o una squadra.Tienine esattamente uno.
template <k>: unknown agent '<a>' / unknown team '<t>'Il modello nomina qualcosa di mancante.Correggilo.
template <k>: two params with the same nameI nomi dei parametri devono essere unici.Rinominane uno.
template <k>: deliver: unknown role '<r>'Il report va a un ruolo non dichiarato. Vedi Destinatari.Correggi il ruolo.
channel <type>: unknown agent '<a>'Un canale nomina un agente mancante.Correggilo.

Errori: trigger

MessaggioSignificatoCorrezione
trigger <k>: on needs exactly one of cron, collection, webhook, payment, approval, call, dateNessuna sorgente o più di una.Tieni una sola sorgente.
trigger <k>: needs exactly one of start (an agent, team or job), notify (an email), write (save a record) or charge (credits)Nessuna azione o più di una.Tieni una sola azione.
trigger <k>: start needs exactly one of agent, team, jobstart non nomina nessuna destinazione o ne nomina più di una.Tienine una.
trigger <k>: unknown agent '<a>' / unknown team '<t>' / unknown job '<j>'La destinazione non esiste.Correggila.
trigger <k>: unknown collection '<c>'on.collection non è dichiarata.Correggila.
trigger <k>: on.date reads unknown collection '<c>'on.date.collection non è dichiarata.Correggila.
trigger <k>: unknown approval '<a>'on.approval non è dichiarata.Correggila.
trigger <k>: '<p>' is not a plan or packon.payment non è la chiave di un piano o di un pacchetto (né *).Correggilo.
trigger <k>: op and where apply to a collectionop o where senza on.collection (where è ammesso anche con call e date).Rimuovili o aggiungi la raccolta.
trigger <k>: decision applies to an approvaldecision senza on.approval.Rimuovilo.
trigger <k>: '<c>' is not a phone channelon.call non nomina un canale phone.Correggilo (i canali telefonici non sono ancora disponibili).
trigger <k>: callEvent applies to a callcallEvent senza on.call.Rimuovilo.
trigger <k>: <a> writes <c>, which starts it — add a where filterL’agente scrive nella raccolta che lo avvia: si avvierebbe da solo a ogni esecuzione.Aggiungi un filtro on.where (o usa op: update).
trigger <k>: write to unknown collection '<c>'write.collection non è dichiarata.Correggila.
trigger <k>: write cannot target an instance's collectionI record di un’istanza sono scritti dall’agente dell’istanza.Usa un’altra raccolta.
trigger <k>: writes the collection that starts itUn write nella raccolta di on.collection creerebbe un ciclo.Usa un’altra raccolta.
trigger <k>: charge needs an event with a user (a record, an approval, a payment, a date)Un trigger cron o webhook non ha un utente a cui addebitare.Usa un’altra sorgente.

Errori: destinatari

Questi errori vengono da triggers[].notify.to, schedules[].deliver.to e templates[].deliver.to. <where> è, per esempio, trigger <k>: notify.

MessaggioSignificatoCorrezione
<where>: unknown role '<r>'role:<r> nomina un ruolo non dichiarato.Correggilo.
<where>: 'record.<f>' needs an event with a record (collection, date, approval, call or webhook)Non c’è un record da cui leggere l’indirizzo.Usa owner, admins o role:<key>.
schedule #<i>: deliver needs an agent's reportdeliver su una pianificazione senza agent.Aggiungi l’agente o rimuovi deliver.
schedule #<i>: deliver needs to (admins or role:<key>) — an app-wide schedule has no ownerUna pianificazione non ha un proprietario a cui inviare.Imposta deliver.to.

Errori: fatturazione, limiti, pianificazioni

MessaggioSignificatoCorrezione
billing: free cannot be combined with other modesfree insieme a un’altra modalità.Tieni free da solo, o rimuovilo.
billing: credits mode needs a way to get credits (packs, plans with credits, or signupCredits)Gli utenti non potrebbero mai ottenere crediti.Aggiungi pacchetti, crediti nei piani o signupCredits.
billing: subscription mode needs plansNon c’è niente a cui abbonarsi.Aggiungi billing.plans.
billing.costs: unknown agent '<a>'Una chiave di costo agent:<a> nomina un agente mancante.Correggila.
billing.costs <k>: perUnit field '<f>' is not a form fieldIl prezzo segue un campo che il modulo non ha.Correggi perUnit.field.
billing.costs <k>: perUnit field '<f>' must be a number fieldSi può moltiplicare solo un numero.Usa un campo number.
billing.costs <k>: perUnit is a fixed price per unit — not metered as wellperUnit e metered insieme.Tienine uno.
limit: unknown agent '<a>'action: agent:<a> nomina un agente mancante.Correggilo.
limit: unknown collection '<c>'action: create:<c> nomina una raccolta mancante.Correggila.
limit <action>: '<p>' is not a plan or packUna chiave di plans non è un piano o un pacchetto.Correggila.
schedule: unknown agent '<a>' / schedule: unknown job '<j>'La pianificazione nomina qualcosa di mancante.Correggilo.

Avvisi

Gli avvisi vengono dai controlli di progettazione. Un’app pubblicata continua a funzionare quando qui viene aggiunto un nuovo controllo.

MessaggioSignificatoCorrezione
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)Pagine, strumenti, select o trigger leggono record degli utenti che niente nell’app crea: restano vuoti.Aggiungi qualcosa che scrive, o cambia il proprietario in 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 userUn modulo aperto a tutti gli utenti scrive in un catalogo che riempiono solo gli amministratori.Imposta roles: [admin], elimina il modulo, o imposta 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 userLo stesso, per un modulo limitato a ruoli non amministratori.Lo stesso.
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 approvalsGli amministratori entrerebbero in un menu vuoto.Aggiungi il ruolo di amministratore alle pagine che usano.

App per telefono

Quando il manifest ha spec.mobile, questi problemi compaiono come avvisi in App Studio, e l’esportazione dell’app per telefono li rifiuta ("the phone app settings are not valid").

MessaggioSignificatoCorrezione
mobile.appId '<id>': reverse-DNS, lower case, at least three parts (e.g. eu.webrobot.myapp)L’identificativo per gli store non è ben formato.Usa qualcosa come eu.example.myapp. Non può cambiare dopo la pubblicazione.
mobile.capabilities: '<c>' is not an approved capabilityNon è nell’elenco approvato.Rimuovila.
mobile.capabilities: '<c>' twiceDichiarata due volte.Rimuovi il duplicato.
mobile.capabilities <c>: a reason is required (the phone shows it when asking the permission)Il telefono chiede all’utente questo permesso e deve dire perché.Aggiungi reason.
mobile.capabilities <c>: needs '<d>' tooUna capability dipende da un’altra (backgroundLocation richiede location).Aggiungila.
mobile.version '<v>': x.y.zIl formato della versione.Usa 1.2.3.
mobile.capabilities: '<c>' — no part of the app can use it yet: remove itcontacts, bluetooth, backgroundLocation, localNotifications e speech non sono ancora utilizzabili.Rimuovila.
mobile.capabilities: '<c>' is declared but nothing in the app uses it (the stores refuse unused permissions): remove itUn permesso che nessuno usa.Rimuovilo, o aggiungi ciò che lo usa.
mobile.capabilities: <feature> (<where>) needs '<c>' in the phone appL’app usa una funzione del telefono (un campo posizione, un campo codice a barre, un campo foto, un pulsante per aggiungere al calendario, un pulsante di condivisione, il blocco dell’app) senza dichiararne la capability.Aggiungi la capability.

Errori di pubblicazione

La pubblicazione esegue di nuovo la validazione, poi crea le parti dell’app sulla piattaforma. Un errore nomina il passaggio che è fallito: <step>: <message>.

MessaggioSignificatoCorrezione
save a draft firstNon c’è una bozza salvata.Salva, poi pubblica.
stored draft is not valid JSONLa bozza salvata non si può leggere.Salva di nuovo la bozza da App Studio.
validate: <errors>La bozza ha errori di validazione (sono elencati i primi cinque).Correggili.
app tools: <message>Non è stato possibile configurare l’endpoint degli strumenti dell’app.Riprova; se persiste, contatta il supporto.
agent <a>: <message>La piattaforma ha rifiutato il profilo inline dell’agente.Leggi il messaggio: di solito riguarda la definizione inline.
team <t>: <message>La piattaforma ha rifiutato il profilo della squadra.Lo stesso.
team <t>: agent <a> has no inline crewIl profilo inline di un membro della squadra non ha crew.Dai all’agente almeno una crew.
pipeline: inline pipeline is not YAML stages or a pipeline specLa pipeline inline di un job non si può leggere.Correggi lo YAML.
pipelines: <message>La piattaforma ha rifiutato le pipeline dei job.Leggi il messaggio.
job <j>: manifest applied without this JobLa piattaforma non ha creato il job.Pubblica di nuovo; controlla la pipeline.
api key: <message> / credential: <message>Non è stato possibile creare la chiave API dell’app (solo alla prima pubblicazione).Controlla il tuo ruolo nell’organizzazione; riprova.
validate published: <errors>Il manifest dopo la pubblicazione non è valido.Segnalalo: non dovrebbe succedere.
invalid slugLo slug non rispetta il formato.3–40 caratteri, lettere minuscole, cifre, -.
slug already takenUn’app di un’altra organizzazione ha già questo slug.Scegli un altro slug.
metadata.slug must be <slug>Lo slug del manifest è diverso da quello dell’app.Mantieni lo slug con cui l’app è stata creata.
kind must be VerticalApp / apiVersion must be webrobot.eu/v1alpha1L’intestazione del documento è sbagliata.Usa i valori esatti.
host <h> is already used by another appspec.host o un dominio appartiene a un’altra app.Rimuovilo, o liberalo prima nell’altra app.
the caller has no organizationIl tuo utente non ha un’organizzazione.Unisciti a una o creane una.