Developers · Build with AI
When Your AI Gets Stuck
Last updated 18 November 2026
Read the logs, understand common errors, give your AI better context, and know when to ask for help.
Sometimes your AI tries a fix, then another, and the problem stays. This page shows how to get it unstuck: read the logs, know what the common errors mean, give the AI better context, and know when to ask a person.
Step 1: Ask Your AI to Read the Logs
The logs are the first place to look. They show errors from your pages, including Liquid errors. Your AI can read them through CloudShell, so you never need to open them yourself.
Check the status of my last deploy, then read the logs on my selected instance since that deploy. Quote each error exactly, say which file it comes from, and explain it in plain words. Do not change anything yet.
If the logs show nothing useful, your AI can add its own messages to the code with the log tag, deploy, and read them. Ask it to remove those messages when the problem is fixed, and never to log a secret.
Add log messages to the page at ADDRESS so we can see what happens step by step. Deploy, open the page once, and read the logs. When we find the problem, remove the log messages.
Common Errors and What They Mean
A Tool Is Refused
Your role on that site does not allow it. By default, reading logs needs Viewer, setting environment variables needs Editor, and deploying needs Developer or above. Ask the account owner to change your role.
The Change Went to the Wrong Site
Every tool works on the selected site, and the selection is remembered across conversations. Ask your AI which site is selected, select the right one, and deploy again.
A Deploy Fails
Ask your AI to check the deploy status and the logs. Check that the file path starts with app/ or modules/. A large file, over about 32 KB, should go through an upload link. If it is sent directly, it can arrive incomplete.
Liquid Syntax Error (Line 4)
The deploy found a mistake in a file and names the line. For example, Liquid syntax error (line 4): Unknown filters: not_a_filter means the code uses a filter that Insites does not have. Ask your AI to check the Logic Engine for the right filter.
The Deploy Refuses a YAML File
YAML is the settings part at the top of a file, between two lines of dashes. The deploy refuses some spellings, such as a value that starts with a colon, a !ruby/object tag, or an alias that points at nothing. The error message names the fix, so give your AI the exact message.
Two Files Claim the Same Table or Form Name
The deploy fails when two files define a table or a form with the same name. Ask your AI to find both files and keep one.
The Page Answers Not Found
The address does not match the page. Check that the slug in the page file matches the address, that the page is in the right folder, and that the page answers the right method, such as GET or POST.
405 Method Not Allowed
The page exists but does not accept that kind of request. Each page answers one method. A form that posts needs a page with method: post.
The Page Is Blank
The page tries to show a partial, but the path to the partial is wrong or the partial is empty. Ask your AI to check the path. Also check that the layout shows the page content.
Values From a Partial Are Empty on the Page
Values made inside a partial stay inside it. The page cannot see them. The partial must return the value, for example by being called with the function tag.
A Form Posts, but the Person Seems Signed Out
The form is missing its security token, called the authenticity token. Without it, Insites treats the person as signed out for that request. Every form that sends data needs the hidden authenticity_token field.
A Protected Page Lets Nobody In
An authorization policy must print exactly the word true to let someone in. Anything else, even true with an extra line after it, counts as no. Ask your AI to make the policy print only true or false.
A Secret Reads as Blank
The constant is not set on this site, or its name is spelled differently. Names must match exactly: API_KEY and Api_Key are two different constants. Constants belong to one site, so set it again on production.
Emails Do Not Arrive on Staging
A staging site sends email only to the test recipients set in the site settings. Add your address there. See Staging vs. Production.
A New Image Still Shows the Old One
Files are cached for a long time. After you upload a file again, its plain address can keep showing the file you replaced. Ask your AI to show every file through the asset_url filter. That address changes when the file changes.
Give Your AI Better Context
Most stuck moments come from missing information. Give your AI more of it.
- Point it at the Logic Engine again. Each topic has a gotchas file of known problems, in
skills/insites/references/. If your AI saved a copy earlier, ask it to read the latest version from the repository. - Point it at the guide. Paste the address of the docs page for the job, such as
/developers-guide/passwordless-sign-in. - Paste the exact error. Copy the words, not your memory of them.
- Say what you expected and what you saw. Give the address of the page.
- Fix one thing at a time. Ask for one change, then check it.
- Ask it to explain before it changes code. If the explanation does not make sense, the fix will not either.
Stop changing code for a moment. Read the gotchas file for this topic in the Insites Logic Engine at https://github.com/insites-io/insites-logic-engine under skills/insites/references/. Then tell me what you think the cause is, what you have already tried, and what you will try next. Wait for me to agree before you change anything.
When to Ask a Person for Help
Ask a person when your AI has tried the same fix more than once, when the logs show an error nobody can explain, or when real users or real data are affected.
- A teammate. If someone else on your Insites account knows the project, show them the error and what you tried.
- Insites support. Email [email protected]. Quote your account number. You find it in the Identity section of the Account page in the Console.
Put these in your message, so a person can help quickly:
- The site name and its web address.
- Your account number.
- What you expected, and what happened instead.
- The exact error from the logs, and the time it happened.
- The prompt you gave your AI, and what it changed.
- If you use GitHub, the commit that caused the problem.
Your AI can write this message for you:
Write a short support message about this problem for Insites support. Include the instance name and address, what I expected, what happened, the exact errors from the logs with their times, and the files and commits you changed. Use plain words.