FAQ
Answers are collapsed so the list stays scannable. Open one, or expand everything at once.
Getting started
Section titled “Getting started”What do I need before I install MAIA Plus?
Three components: a PostgreSQL instance with the pgcrypto and vector extensions, a host that can run the packaged binary, and Python 3.11+ if you want to train assignment models. The embedding dimension configured at install time must equal the dimension of the embedding model you select later. See Installation.
Do I need to install Node.js?
No. The application ships as a Bun-compiled binary; the runtime is inside the executable. Python is separate and only used for model training.
The service exits with “Illegal instruction”. What happened?
You are running the standard binary on a CPU without AVX2. Switch to the baseline artifact (mwtsolutions-maia-linux-baseline or mwtsolutions-maia-win-baseline.exe); no data change or reinstall is required.
Providers and models
Section titled “Providers and models”Does an active provider mean requests are succeeding?
No. An active provider or an assigned route describes configuration. Only a completed request proves the provider answered. See Diagnostics.
What is the difference between an LLM route and an embedding route?
The LLM route produces text — answers, summaries, classification. The embedding route produces vectors, which is what retrieval needs. Retrieval features fail without an embedding route even when the LLM route is perfect. See AI providers.
I changed the embedding model and search stopped working. Why?
Vectors from two different models are not comparable. The stored vectors must be regenerated with the new model, and the vector column dimension must match it. Re-index the knowledge base and the ticket index.
Can I use a different model for agents and for single-step calls?
Yes. Agent and Completion are separate routes, so an installation can put an expensive model behind agents and a cheap one behind bulk steps.
Agents, tools and automation
Section titled “Agents, tools and automation”What is an agent, in one sentence?
A persona plus a policy: instructions, tools, knowledge scope, autonomy and limits — everything except the model, which comes from a provider route. See Agents.
My agent answers but never changes anything. Why?
Either the tools it needs are not granted, or a write tool is not unlocked by a procedure. An agent with no write procedure produces notes and text only.
What is MCP and do I need it?
The Model Context Protocol is a standard way to expose external tools to an AI step. You need it only when the capability lives in another system that already publishes an MCP server; otherwise the built-in tools are enough. See Tools and MCP.
Why does my automation exist but never fire?
An inactive automation rejects calls. An active one still needs ServiceDesk Plus to call its endpoint, which requires a custom trigger and a webhook action configured on the SDP side, with the key for that specific target.
What is the difference between an agent automation and a legacy flow?
An agent automation lets the model decide how to reach the goal; a legacy flow follows a fixed deterministic path with category prediction. The flow path is being retired in favour of workflows.
Knowledge
Section titled “Knowledge”I uploaded a document and it never appears in answers. What should I check?
Status must read Indexed, the visibility must allow the audience, the portal scope must match the request, and the embedding route must be configured. See Knowledge Vault.
Can MAIA Plus ingest a folder from disk?
Yes — a file source with local_path and file_extensions. The folder must be readable by the service account, and file sources default to internal visibility. See Knowledge Sources.
Does an empty approval queue mean everything is indexed?
No. It means nothing is waiting for review in that queue. Indexed state and approval queue are different surfaces.
Workflows
Section titled “Workflows”Why did my workflow end early without an error?
A branch activated an output with no edge. The run is technically successful and stops there. Check which handle was active in the run timeline.
Why does a step fail with “unresolved expression”?
The template reads a value that does not exist on that path — a skipped node, a renamed node id, or a missing payload field. Reference $node["id"] instead of $json, or guard the read. See Expressions and context.
Is a test run safe?
Only if you bound it. Mocked steps are isolated; everything else uses real models, tools and integrations. Use an execution range that stops before the first write. See Testing and debugging.
The run is stuck at “Waiting for input”. Is it broken?
No. It is waiting for an approval decision on a write tool. Decide it under Approvals, or change the policy if unattended operation is intended.
Will workflows replace agents and automations?
Automations already reference a workflow_key, and workflows are the surface for expressing both deterministic steps and agent behaviour. Registered agents and automations remain fully supported in 1.1.1, and an automation may point at either an agent or a workflow.
Security and operations
Section titled “Security and operations”What do HTTP 401 and 403 mean?
401 means the session or key is missing, invalid, revoked, or bound to a different target. 403 means it is valid but the resource is outside its scope. See Permissions.
Does the NER service need to be running?
No. Without it, data protection runs in a faster regex-only mode. With it, named entities such as person names and addresses are also detected.
Where do I see what the system actually did?
Enterprise Audit: runs, approvals, inbound requests and external actions, each with actor, time and business result. See Enterprise Audit.
Which product version do these articles cover?
MAIA Plus 1.1.1. UI observations are time-specific; behaviour in another deployment or build can differ.