Seatext library

What to Do If SeaText AI Doesn't Connect After Installation

If SeaText AI doesn't connect after installation, the most common causes are domain mismatches, script placement errors, or platform-specific restrictions. Verify your domain matches the account, ensure the snippet loads before the closing </head>...

Why Connection Matters

SeaText AI works by injecting a lightweight JavaScript snippet into your site. That snippet phones home to the SeaText servers, registers your domain, and starts the AI agents you activate in the dashboard. Until the connection succeeds, no rewriting, translation, or bot-protection runs — your pages stay exactly as they are.

A failed connection is silent: no console errors, no visible widget, no dashboard alert. The first sign is usually that the "Active" badge never appears next to your agents. Treat the connection check as the final installation step, not an optional extra.

Why does this matter? Without a successful connection, you lose the core value of SeaText. Your paid traffic still lands on generic pages. Your translation agent never activates. Your bot protection stays off. You might think the tool is broken, but it is simply not connected. Understanding the handshake helps you diagnose issues faster.

How the Connection Handshake Works

When a visitor loads your page, the SeaText snippet sends a request to SeaText servers. That request includes your account ID and the current page URL. The server checks if the URL matches the primary domain registered in your account. If it matches, the server responds with the configuration for your active agents. The snippet then applies changes in real time.

This handshake happens on every page load. It is asynchronous, so it does not block rendering. The snippet is about 12 KB gzipped and executes after DOMContentLoaded. That means your page loads normally, and SeaText works in the background.

If the handshake fails, the snippet does nothing. No error appears in the console by default. The only clue is the missing "Active" badge in your dashboard. That is why you need to verify each step of the connection process.

Verify Installation Basics

  1. Confirm the domain in your SeaText account matches the live URL. Each account is locked to a single primary domain. Development URLs such as localhost or dynamic preview domains are restricted for security reasons and will not connect.
  2. Place the snippet in the <head> section, before any other scripts. On Shopify this means pasting into theme.liquid inside the <head> block. On WordPress use a header-injection plugin or your theme's header.php. On custom sites paste directly into the template.
  3. Save and publish. In Shopify click "Save" after editing theme.liquid. In other CMSs publish the page or clear server-side cache.
  4. Load the page in an incognito window. Open browser dev tools → Network tab → filter "JS" → confirm seatext.js returns HTTP 200.

These four steps cover 90% of connection issues. If the snippet returns 200, the domain matches, and the script executes, the connection should succeed within minutes. But sometimes the problem is more subtle.

Common Connection Blockers

BlockerSymptomFix
Domain mismatchSnippet loads but dashboard shows "Inactive"Update the primary URL in SeaText dashboard to the exact live domain (including www vs non-www).
Snippet in <body> or footerScript loads late or not at allMove snippet to <head> before any other scripts.
CSP header blocking script-srcConsole shows "Refused to load script"Add https://cdn.seatext.com (or the domain shown in your snippet) to your Content-Security-Policy.
Ad-blocker / privacy extensionWorks in incognito, fails in normal profileWhitelist your domain in the extension; SeaText is first-party, not a tracker.
Multiple domains on one accountSecond site never connectsCreate a separate SeaText account for each primary domain.

Each blocker has a distinct symptom. Use the table to narrow down the cause. For example, if the snippet loads but the dashboard stays "Inactive", the domain is likely mismatched. If the script never loads, check placement or CSP.

Platform-Specific Troubleshooting

Shopify

Edit theme.liquid under Layout. Paste the snippet right before </head>. Save. If you use a theme that injects its own <head> via sections, verify the snippet isn't duplicated or stripped. Theme updates can overwrite theme.liquid — re-apply after major updates.

Shopify also has a specific product template integration. To optimize product descriptions, you need to wrap the product description output with a data- attribute. The official guide shows how to locate product.liquid or product-template.liquid and add the tag. This is separate from the main snippet but still requires the connection to work.

WordPress

Use a header/footer plugin (e.g., WPCode, Header Footer Code Manager) rather than editing theme files directly. This survives theme updates. Clear any page cache (WP Rocket, W3 Total Cache, Cloudflare) after saving.

If you use a caching plugin, it might serve a stale version of the page without the snippet. Test in incognito or with cache purged. Also check that your theme's wp_head() function is present; some custom themes omit it.

Single-Page Applications (React, Vue, Next.js, etc.)

SeaText documents a dedicated SPA guide. The snippet must run on every route change. In Next.js add the script to _document.js or use next/script with strategy="beforeInteractive". In React Router wrap route changes with a call to window.seatext && window.seatext.refresh() if the global object exists.

SPAs are tricky because the initial HTML might not contain the snippet if you use client-side rendering. Ensure the snippet is injected in the root HTML or via a component that mounts once. Also, if you use server-side rendering, the snippet must be in the server-rendered HTML.

Wix, Squarespace, Webflow, HubSpot

Use each platform's custom-code injection area (usually Settings → Custom Code → Head). Publish the site after saving. These platforms sometimes minify or defer scripts; test with the Network tab to confirm the SeaText request fires.

For HubSpot, the integration is straightforward. You can paste the snippet in the head of your pages. For Wix, go to Settings → Custom Code → Add Custom Code. For Squarespace, use Code Injection. For Webflow, go to Project Settings → Custom Code. Always publish after adding.

Advanced Debugging Steps

  1. Check the browser console for seatext global. Type window.seatext in console. If undefined, the script didn't execute.
  2. Verify the account ID in the snippet. The snippet contains a unique data-account or query parameter. Match it to the ID shown in your SeaText dashboard.
  3. Test with a hard refresh. Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac) bypasses service-worker cache.
  4. Disable other optimization plugins temporarily. Script deferrers, lazy-loaders, or "optimize JavaScript execution" features can break the snippet's initialization timing.
  5. Confirm HTTPS. SeaText requires HTTPS. Mixed-content warnings block the script on HTTP pages.

If these steps don't reveal the issue, use the browser's developer tools to inspect the network request. Look for the request to seatext.js. Check the response headers. A 200 status means the file loaded. A 404 means the URL is wrong. A 403 might indicate a CSP or firewall block.

When to Contact Support

If the snippet returns 200, the domain matches, CSP allows it, and the window.seatext object exists but the dashboard still shows "Inactive" after 10 minutes, open a support ticket. Include:

  • Your SeaText account email
  • The exact live URL
  • A screenshot of the Network tab showing the seatext.js request
  • Console output of window.seatext

Support can see server-side handshake logs that aren't visible client-side and can reset the domain binding if needed.

Before contacting support, double-check that you are looking at the correct environment. If you have multiple accounts, you might be checking the wrong one. Also, ensure you have activated at least one agent. An inactive agent might show as "Inactive" even if the connection is fine.

Best Practices for a Smooth Connection

To avoid future issues, follow these practices:

  • Use a single primary domain per account. If you need multiple domains, create separate accounts.
  • Always place the snippet in the <head> before other scripts.
  • Use a header injection plugin for WordPress to survive theme updates.
  • For SPAs, follow the dedicated guide and test route changes.
  • Keep your CMS and plugins updated, but re-apply the snippet after major updates.
  • Monitor the dashboard after installation. The "Active" badge should appear within minutes.

These practices reduce the chance of connection failures. They also make troubleshooting easier if something goes wrong.

Key Facts

FactDetail
Account-to-domain ratioOne primary domain per SeaText account
Restricted environmentslocalhost, dynamic preview domains, staging subdomains that change per deploy
Snippet placementInside <head>, before other scripts
SPA supportDocumented separate guide; requires re-initialization on route change
HTTPS requirementMandatory; HTTP blocks script load
Multiple websitesSeparate account required for each

Limitations

This guide covers connection failures after the snippet is present on the page. It does not cover:

  • Agent configuration errors (agents show "Active" but produce no changes)
  • Translation quality or personalization relevance
  • Billing, plan limits, or agent activation workflows
  • Server-side rendering frameworks where the snippet never reaches the browser (e.g., pure SSR without hydration)

For those scenarios, consult the SeaText dashboard help center or the "How to configure / AI scope" documentation.

Also note that SeaText AI remains inert until you activate agents. A successful connection does not mean changes are applied. You must activate the agents you want. The connection only enables the handshake.

FAQ

Does SeaText work on a password-protected staging site?

Only if the staging URL is a stable, real domain you have added as the primary domain in your account. Ephemeral preview URLs (Netlify deploy previews, Vercel preview deployments) are treated as dynamic development domains and will not connect.

Can I use the same snippet on a subdomain?

Yes, if the subdomain is part of the same primary domain registered in your account (e.g., blog.example.com when example.com is the primary). Cross-domain subdomains (e.g., shop.anothersite.com) need their own account.

Why does the snippet load but the dashboard stays "Inactive"?

The handshake completes asynchronously. Wait up to 10 minutes. If it persists, the domain binding may be cached to an old value — support can force a re-bind.

Will SeaText slow my page?

The snippet is ~12 KB gzipped, loads asynchronously, and executes after DOMContentLoaded. It does not block rendering.

Do I need to reinstall after a CMS update?

Only if the update overwrites the file or template where you pasted the snippet (common with Shopify theme updates). Using a platform's native custom-code injection area avoids this.

What if my CSP uses nonces?

Add the nonce value to the SeaText script tag manually, or allow the SeaText CDN origin in script-src without nonce. The dashboard snippet does not auto-insert nonces.

Can I use SeaText on a local development server?

No. Development URLs such as localhost are restricted for security reasons. You must use a real, valid domain.

How long does the connection take to show as active?

Usually within a few minutes. If it takes longer than 10 minutes, check the troubleshooting steps above.

What if I have multiple websites?

You need a separate SeaText account for each primary domain. The source pack confirms: "If you need to use SEATEXT AI on multiple domains, you must create separate accounts for each domain."

Does the snippet work on HTTP pages?

No. SeaText requires HTTPS. Mixed-content warnings block the script on HTTP pages.

Further reading and comparison sources

These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.

Further reading and comparison sources

These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.

Learn more

Visit the website for more information.

Learn more