Troubleshooting

This guide covers the problems you’ll most often hit with the Daeda AI Automation Suite.

Use the tables first.

Then use the deeper notes if needed.

Quick Triage

Symptom	Most likely cause	First check
MCP server will not connect	Bad config, bad Node version, or stdout pollution	/mcp, Node version, MCP config
Registration fails	Invalid key, revoked key, expired trial, or no paid plan	Daeda AI license key and billing state
No portals appear	No connected client portals	Daeda AI > Master Settings > Connected Portals
Query returns no data	Initial artifact sync still running	status(section="schema")
Metadata looks stale	Plugin-backed table not refreshed	status(section="schema") and refresh_plugins
Portal read fails	Portal sync disabled and no local DB exists	configure_sync_controls and status(section="connection")
Write Plan is blocked	Missing scopes or missing trial/plan entitlement	Daeda AI Write Plan review and re-authorisation

Connection Problems

mcp-pro Does Not Connect

Check	What good looks like
Node.js	Version 20 or newer
Package command	npx -y @daeda/mcp-pro
Env var	DAEDA_LICENSE_KEY is present
MCP client config	Valid JSON or valid client-specific format

Handshake Or Initialize Failures

If you see handshake failures, the most important rule is this:

The MCP stdio server must keep stdout clean.

Only MCP protocol frames can go to stdout.

Any normal logging on stdout can break initialisation.

Symptom	Cause	Fix
handshaking with MCP server failed: initialize response	Non-protocol output reached stdout	Remove or redirect any custom wrapper logging; logs must go to stderr only

Invalid License Key

Problem	Fix
Typo in the key	Copy the key again from Daeda AI
Key was regenerated	Update your MCP config with the new key
Key was revoked	Create a new key in Daeda AI

Registration Blocked By Billing Or Trial

Error pattern	Meaning	Fix
Free trial expired. Choose a Daeda AI plan in HubSpot to continue.	The one-time trial ended and no paid plan is active	Choose a paid plan in Daeda AI
Choose a Daeda AI plan in HubSpot to continue.	No active entitlement exists	Start with a paid plan, or trigger the unused trial by first real MCP registration

Remember:

The free trial starts on first real MCP registration.

It does not start on install.

Portal Problems

No Portals Available

If registration succeeds but no useful portals appear, the workspace likely has no connected client portals yet.

Cause	Fix
No connected client portals	In Daeda AI, open Master Settings and connect a portal
Wrong workspace	Check that the license key belongs to the intended Daeda AI workspace

Portal Not Found In set_portal

Cause	Fix
Wrong portal ID	Use one of the IDs returned by status(section="connection")
Portal not connected to this workspace	Connect it in Daeda AI

Portal Sync Disabled

If sync is disabled for a portal:

Situation	Result
Local DB already exists	Reads can use stale local data
No local DB exists yet	Reads fail

Use:

configure_sync_controls(portalId=<id>, portalEnabled=true, refreshArtifacts=true)

Data Sync Problems

Query Says There Is No Data Yet

This usually means the initial artifact sync is still in progress.

Run:

status(section="schema")

Then check:

What to inspect	What it tells you
Database section	Whether a local DB exists yet
Object sections	Which tables are already populated
Connection section	Which portal is selected

Reads Time Out Or Wait Too Long

Error pattern	Meaning	Fix
Timed out waiting for portal <id> artifact queue drain.	Enabled portal reads waited too long for artifact work	Retry, or switch to the selected portal and let it finish syncing
Portal <id> has no synced data yet. Background sync in progress - retry shortly.	Local DB is not ready yet	Wait and retry

Stale Data On A Disabled Portal

This is expected behaviour.

If portal sync is disabled, the Automation Suite will use stale local data only.

If you need current data, enable sync again.

Plugin Freshness Problems

Metadata Looks Old Even Though CRM Data Looks Current

This is the most common confusion.

CRM object tables and plugin tables do not follow the same freshness rules.

Data	Freshness behaviour
CRM records, associations, workflows	Artifact-backed
lists, owners, pipelines, forms, sequences, inboxes, subscriptions	Plugin-backed

If plugin-backed metadata matters, refresh it manually.

Correct Fix For Stale Plugin Data

Step	Action
1	Call status(section="schema")
2	Identify the plugin-backed tables you need
3	Call refresh_plugins(pluginNames=[...])
4	Poll status(section="schema")
5	Wait until the matching job is COMPLETED and the plugin lastRefreshedAt values advance

refresh_plugins Errors

Error pattern	Meaning	Fix
Plugin '<name>' is an artifact-backed plugin.	You tried to refresh an artifact-backed data source	Do not use refresh_plugins for CRM objects, association_schema, or workflows
Unknown plugin '<name>'	The plugin name is wrong	Use one of the active lightweight plugin names
Portal <id> has sync disabled.	Plugin refresh is blocked on disabled portals	Enable portal sync first
No registered master MCP client could accept a plugin refresh request	No writable master client is available to execute the refresh	Keep the main MCP client connected and retry

Active Lightweight Plugin Names

Use these names with refresh_plugins:

Plugin name	Use for
property-definitions	Property definitions and groups
pipelines	Pipelines and stages
owners	Owner records
portal-info	Portal metadata
action-type-catalog	Supported workflow action catalog
workflow-enrollment-triggers	Workflow trigger catalog
lists	HubSpot lists
sequences	Sequences and steps
communication-subscriptions	Communication subscription definitions
conversation-inboxes	Inboxes, channels, and accounts
forms	Forms and form fields
user-teams-permissions	Provisioning users, teams, and roles

Write Plan Problems

Plan Needs Re-Authorisation

If Daeda AI shows a re-authorisation action, the target portal is missing scopes needed by the plan.

Cause	Fix
Missing read or write scope	Re-authorise the target portal with the requested scopes
Missing schema write scope	Re-authorise with the object schema write scope
Missing list-specific scope	Re-authorise with both list write scope and HubSpot access-group write scope if requested

Plan Execution Blocked Before Trial Starts

Write Plan execution can be blocked if the workspace has no paid plan and the trial has not started yet.

The fix is to start the trial through a real MCP license-key connection, or choose a paid plan in Daeda AI.

Daeda AI Workspace Problems

Cannot Connect Another Portal

Error pattern	Meaning	Fix
This workspace needs a Daeda AI plan or an unused free trial to connect portals	No entitlement is available	Choose a plan or use the unused trial
This workspace can only connect X portals right now	Portal allowance is exhausted	Buy more portal capacity or disconnect another portal

Billing And Trial Confusion

Use Daeda AI as the source of truth for the workspace state.

Question	Where to check
Current plan	Daeda AI > Billing
Trial status and end date	Daeda AI > Billing or Master Settings
Portal allowance	Daeda AI > Billing and Connected Portals
License key count and entitlement	Daeda AI > Master Settings

Read-Only Client Behaviour

Sometimes the MCP process serving your request is not the writable owner of the live local DB.

In that case it uses the published read replica.

Behaviour	What it means
Queries still work	Reads are coming from the replica
Some sync work is deferred or relayed	The writable master client owns local mutation work
Plugin refresh may be relayed	Keep the main MCP client connected

A Good Default Diagnostic Sequence

Use this order:

Step	Command or check
1	/mcp
2	status(section="connection")
3	set_portal(portalId=<id>) if needed
4	status(section="schema")
5	refresh_plugins(...) if plugin-backed metadata matters
6	status(section="schema") again until refresh is replica-verified
7	query(...)

When To Escalate

Escalate to Daeda support when:

Situation	Why it matters
A refresh job stays stuck in REPLICATING or RUNNING for a long time	Replica publication or writable-client execution may be blocked
Artifact-backed data never appears after repeated retries	Initial sync may be failing server-side
Re-authorisation loops even after approving scopes	The portal may still be missing a required HubSpot scope
Registration fails for a clearly valid key with a paid workspace	Account or portal mapping may be wrong

Related Guide

How The Local Read Database Works