When Your AI Gets Stuck

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 instance 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 Instance

Every tool works on the selected instance, and the selection is remembered across conversations. Ask your AI which instance 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 that used to slip through. 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 instance, or its name is spelled differently. Names must match exactly: API_KEY and Api_Key are two different constants. Constants belong to one instance, so set it again on production.

Emails Do Not Arrive on Staging

A staging instance sends email only to the test recipients set in the instance 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 the old version. 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 https://docs.insites.io/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 support@insites.io. 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 instance 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.

Related

• CloudShell Tools
• Creating Application Logs
• Insites Logic Engine
• Safety Rails for AI Builds
• What to Ask Your AI
• Insites in Plain Words