Stuck? Common problems and how to fix them

Most of what stalls an implementation is not a product question. It is a credential nobody has at hand, a database that refuses outside connections, a person who needed to be in the setup and wasn't. The good news: almost everything has a known path. Find your symptom below.

1. Credential rejected or nobody has access

Why it happens:

• The credential was pasted wrong: a trailing space in the password, a truncated key, a token from another account.
• The token or OAuth authorization expired or was revoked.
• The account used lacks permission in the source tool (it needs to be an admin or have API access).
• The person who has access is not part of the setup.

What to do:

• Use Share setup link. When adding the source (Sources → Add source → pick the connector), click Share setup link on the access step and send the link to whoever holds the credential: IT, the account admin or, at an agency, the client. They don't need a Nekt account, they fill in the fields or sign in, and the password never travels by email or chat. The link lasts 24 hours; after that, generate a new one from the same draft.
• Expired authorization: reconnect the account on the source page and rerun.
• Check that the connected account has an admin role or API access.
• When pasting a password or key, paste the whole value, with no spaces before or after.

2. Database won't connect

Why it happens: the database doesn't accept connections from Nekt. Either the firewall doesn't allow Nekt's IP, or the database sits on an internal network with no outside access.

What to do:

• Allow Nekt's public IP on the firewall. It is shown in the Helpful resources section of the source setup screen.
• If the database can't be exposed to the internet, use an SSH tunnel: a small machine (VM) that reaches the database and accepts SSH. Database connectors (Postgres, MySQL, SQL Server, Oracle, Firebird, SAP HANA and others) have the SSH Host, SSH Port (default 22), SSH Username and SSH Password or SSH Private Key fields. With a tunnel, the database host is usually 127.0.0.1.
• The private key must be PEM-formatted (Ed25519, ECDSA or RSA). Paste the whole block, from -----BEGIN to -----END.
• Database on AWS with no public access: VPC peering is an option. Talk to the Nekt team.

3. The connector I need doesn't exist

From simplest to most work:

Path	When to use it
Generic REST API	The system has an API. You set the base URL, the authentication (token, API key, OAuth and others) and pagination.
Webhook	The system can send events when something happens.
Google Sheets or CSV	A temporary bridge for data that lives in a spreadsheet or export today.
Python notebook	Call an API with your own logic.
Request the connector	Tell the Nekt team which system and which data you need; they evaluate and prioritize.

Start from the use case. Often only two or three tables of the system matter, and a simple bridge works until the connector exists.

4. Source connected, tables empty

Why it happens: there hasn't been a successful run yet. Tables show up in the catalog as soon as the source is set up, but data only arrives after the first load completes.

What to do: check the source's run history. If the first load is still running, wait: for large sources it can take hours. If it failed, go to item 6.

5. New column or deleted data not showing

• New columns: if the source syncs all fields, new columns come in automatically ("Auto-add fields"). With incremental sync, only new rows get the column filled. To backfill history, run a full sync.
• Records deleted at the source stay in the lake until a full sync. If that matters, schedule a weekly or monthly Additional Full Sync.
• Table that can't be incremental: incremental sync needs a field that says when each record changed. If the API doesn't provide it, only full sync is possible.

More in the guide Sync types: full vs incremental.

6. Run failed or pipeline deactivated

1. Open the failed run on the Runs page and read the analyst summary: what happened and the recommended actions.
2. Follow the actions in order and rerun.
3. Pipeline deactivated on its own: each pipeline has, in its Settings tab, a Max consecutive failures limit. When it is reached, the pipeline is deactivated. Fix the cause and reactivate it from the trigger (Details → Trigger → Edit trigger).

• If the source is down at certain times (a database that shuts down on weekends, for example), schedule runs only when it is available.
• A failure in a pipeline that depends on another is usually a cascade: fix the upstream one first.
• Turn on alerts for important pipelines: the Alerts toggle on the resource page, or global alerts in Settings → Alerts.

More in the guide Monitoring pipelines and runs.

7. API rate limits

What to do: reduce the volume per run. Many connectors have options such as a lookback window, requests per minute and parallelism: start conservative and increase gradually. Avoid syncing more often than the decision needs, and prefer incremental.

8. MCP won't connect or the AI can't see tables

Cause	What to do
The MCP is not enabled	In Nekt, click MCP at the top right → Manage MCP Gateway → Enable now. The MCP Server is part of paid plans.
Your AI tool's plan doesn't accept custom connectors	Claude (custom connector, in the app or browser) and ChatGPT (Plus, Team or Enterprise) are documented; Cursor, Codex and others connect with a token. Consumer versions of some AIs don't accept custom connectors: check your plan first.
Signed in with the wrong account	The connection inherits the permissions of whoever created the token. Reconnect with the right account. If the token's creator left the workspace, it stops working.
Token with a restricted scope	Custom-scope tokens only see what was granted and can't reach sources, transformations, runs or alerts. Edit the token in Access tokens or use a full-access one during implementation.
Data permissions	On the Growth plan, permissions also apply to the AI. Check Workspace → Permissions.
The data hasn't loaded yet	See item 4.

To see which token is in use: Access tokens → View token access.

9. The AI answers wrong

Why it happens: almost always missing business context. The AI doesn't know what counts as an active customer, a sale or a qualified lead, or which table is the official one.

• Write a context document with the definitions and rules of your use case, and update it every time an answer comes out wrong because of a rule.
• Test with questions whose answer you already know before trusting new ones.
• For recurring questions, save the query as a ready table in the Gold layer and point the AI at it: faster and more consistent.
• Several short, focused documents work better than one huge document.

10. Credits higher than expected

How it works: 1 credit = 1 pipeline run (source, query, notebook, history or destination). There is no charge per row, per number of connectors or per user. Failed runs and a source's initial load don't consume credits. Usage shows in Settings → Billing.

Why it came out high: almost always frequency. An hourly source runs 168 times a week; a daily one, 7.

• Pick the frequency by the decision: if the report is read once a day, updating once a day is enough.
• Run only on business days and hours if nobody uses the data on weekends.
• Chain transformations by event (run when the source finishes) instead of fixed times.
• Turn off pipelines nobody uses anymore.

More in the guide Triggers and scheduling without waste.

11. When to reach the Nekt team

Reach out when the error comes back after fixing the configuration, when you need a new connector, when it involves plan or billing, or when something can only be done by the Nekt team. To solve it faster, send along:

• the name of the source or resource;
• what you already tried;
• the error message;
• the run link, if there is one.

Never send passwords or tokens by chat or email.

↗ Dig deeper in the docs: frequently asked questions