Common error messages and what they mean

This file maps on-screen errors / toast messages / banner copy to their meaning and fix. Tyler refers to this when a user reports an error.

Authentication / sessions

"Clerk: Handshake token verification failed"

Backend couldn't verify your session JWT. Usually means the Clerk instance on the frontend doesn't match the Clerk instance on the backend (dev vs. production key mix-up, or a stale browser cookie).

Fix:

1. Clear site data (F12 → Application → Clear storage → Clear site data).
2. Sign in again.
3. If it persists, contact admin — the deployment's Clerk keys likely need realigning.

"Authentication required" (401)

No active session. Sign in again. Sessions auto-refresh, so seeing this after being signed in usually means the cookie was cleared or the session expired (rare — Clerk sessions are long-lived).

"Your seat has been suspended by your organisation admin" (403 SEAT_SUSPENDED)

An org admin has paused your seat. Read-only access remains but you can't take any actions. Contact your admin.

Connections

"Connect Zoho CRM first" / "No CRM connected"

You're trying to use a feature that needs a CRM (e.g. target a view for outreach, or push a prospect). Go to Connections and connect Zoho, Pipedrive, or HubSpot.

"Token expired — please reconnect"

The OAuth token for a provider has expired. Open Connections, click Disconnect then Connect on the affected provider. HubSpot tokens rotate on every use — if HubSpot shows this error after a period of inactivity, simply reconnect.

"No Zoho views available. Please connect Zoho CRM first."

The backend couldn't list your Zoho views. Check:

1. Zoho connection is green on the Connections page.
2. You have custom views defined on the Leads module in Zoho (at least one).
3. If Zoho is connected but still no views, try disconnecting and reconnecting — the token scope might be wrong.

"Failed to start [CRM] connection — no redirect URL returned"

The OAuth handshake with the CRM failed before the redirect URL was generated. Usually a misconfigured redirect URI in the CRM app registration. Contact support if this persists after reconnecting.

"Push to CRM failed" / CRM push error in Railway logs

Common causes by provider:

• Zoho: expired token (reconnect), or a field value that doesn't match Zoho's field type (e.g. full ISO timestamp in a date field).
• Pipedrive: scope mismatch on the Pipedrive app (contacts:write needed) — reconnect after confirming scopes in your Pipedrive Marketplace settings.
• HubSpot: industry value not in HubSpot's enum (silently skipped), or a custom property (like linkedin_url) not created on your portal.

Runs and outreach

"No Zoho views specified"

The run tried to start but no views are selected in Run Setup. Pick at least one view.

"Email usage limit reached (X/Y)"

You've hit your daily email cap for your plan. Either:

• Wait until tomorrow (daily reset).
• Upgrade your plan.
• Ask an admin to change your tier on the Team page.

"LinkedIn usage limit reached"

Same as above but weekly cap.

"Microsoft 365 token expired mid-run"

The run errored partway through because your M365 session died. Reconnect Microsoft 365; the already-processed leads aren't retried automatically.

"Run was cancelled before pickup"

You cancelled a queued run before the worker started processing it. Safe — nothing happened.

"Too recent" (lead skipped)

The lead already received outreach in the last 14 days (10 working days). Skipped to avoid spam. If this is wrong, loosen the "recent send" check or manually reset Last_Outreach_Date in Zoho.

"Lead has replied" (skipped)

The lead's email thread has an Incoming direction marker in Zoho — they've replied and shouldn't be emailed again. This is checked live against Zoho's /Leads/:id/Emails endpoint.

Prospecting

"You've used all N prospect searches on your plan this month"

Monthly searches quota exhausted. Upgrade plan, wait for next month, or ask admin for a tier change.

"No results"

Search returned zero companies. Loosen filters — start with fewer constraints (e.g. drop the revenue range or widen headcount) and narrow progressively.

"Select 1-100 prospects to push"

Push-to-CRM needs between 1 and 100 prospect IDs in a single call. Batch larger lists client-side.

Billing

"Stripe rejected the plan change"

The admin tried to change a member's plan but Stripe returned an error. Common causes:

• The org has no active Stripe subscription (still on free tier).
• The plan has no stripePriceId configured (admin-only).
• Payment method on file failed.

"An invitation already exists for this email"

You tried to invite someone who's already in the pending invitations list. Either cancel the existing invite first or ask the invitee to check their spam for the original email.

"You can't remove yourself from your own organisation"

Admins can't delete their own membership. Transfer ownership first (or have another owner remove you).

Generic

"Failed to save"

Settings PATCH failed. Check Railway logs for the specific reason. Usually a validation error (e.g. exceeded max reference URLs for your plan).

"Something went wrong"

Generic fallback. Check browser console and Railway logs for the underlying error. Likely transient — retry usually works.

Contacting support

If an issue can't be resolved through the steps above, there are two ways to reach the Leadmeister team:

• Email: support@leadmeister.ai — for general questions, billing issues, or anything that needs a human.
• Contact form: available via the Contact button in the left sidebar (signed-in users) or the Contact link in the footer (public site). The form asks for your name, company, phone, and a message.

Include as much context as possible: what page you were on, what you clicked, and the exact error message or behaviour you saw.