Troubleshooting

Each entry here is a message midcode shows, or something you see, with why it happens and what to do. If yours isn’t here, send a report: it has what it takes to find out.

The project doesn’t start

Start with the log. The button at the right of the top bar (a dot beside a terminal icon) opens it, and an error opens it by itself. Its first line is the command midcode ran:

$ next dev --port 4310  (/opt/homebrew/bin/node)

What your dev server printed after that is usually the answer. Open a project says how midcode decides what to run.

“Dependencies are missing”

The project has a package.json and no node_modules. Click “Install with pnpm” (or npm, yarn, bun). midcode runs that install in your shell and then starts the server.

“Next.js is not in node_modules. Install the dependencies.” means the same for one package: the folder is there, the framework isn’t. The same button fixes it.

“pnpm isn’t installed on this Mac (or not on your shell’s PATH)”

midcode runs commands the way your terminal would: it asks your shell for its PATH, once, and keeps the answer. A tool installed after that isn’t in it yet.

1. 1

   Check that the command works in a new terminal window.

2. 2

   Try again in midcode. After a failed install it reads your PATH again, so a tool installed a moment ago is found.

3. 3

   If it’s still not found, quit midcode and open it again.

With no Node on the Mac at all, midcode still runs your dev server with its own. It can’t install dependencies, though: that needs your package manager.

“The server stopped (code 1)” or “The server did not answer in time”

Your dev server exited, or never answered. The reason is in the log: a missing env variable, a syntax error in a config, a port your script insists on.

• –

  Run your own dev script in a terminal. If it fails there too, fix that first.

• –

  If it works in your terminal and not in midcode, send a report.

After 25 seconds of “Starting the server…” the canvas says “It’s taking longer than usual” and offers the log. midcode keeps waiting: 45 seconds for its own way of starting a project, 2 minutes for your script.

“A Next server is already running for this project”

Next.js allows one next dev per folder, and yours is running somewhere, usually in a terminal. midcode can’t use that one: it runs without the hook that tells the canvas where each element is written.

• –

  Click “Stop it and use midcode”. midcode stops that process after checking it is a Next.js server.

• –

  Or stop it yourself, then click “Restart” in the log.

If midcode says “Couldn’t stop process …”, close it yourself and try again.

The site shows, but nothing can be edited

A message said: “midcode couldn’t start this project its own way, so it runs your dev script”. For Vite, SvelteKit, React Router, Remix, Astro and Nuxt projects, midcode starts the server with its plugin added. When that doesn’t come up in 45 seconds it falls back to your dev script, so the site still shows, without the marks editing needs.

The log says what went wrong the first time. Common causes: a config that needs something only your script sets up (an env file, another process), or a version of the framework midcode doesn’t know yet. Use “Send report” on that message so it can be fixed.

From the next release there’s a second reason: a .midcode/server.json in a Next.js, Vite, Astro, Nuxt, SvelteKit, React Router or Remix project. With it the site runs the project’s own way, with no marks. Delete the file, then click “Restart” in the log.

“Vite is running, but the site isn’t answering at …”

A Laravel app. Vite only builds its assets; the pages come from PHP at the APP_URL of your .env. Start the site (Herd, Valet, or php artisan serve) and click “Try again”. If APP_URL is a plain http address on this Mac, midcode starts php artisan serve itself, which needs php on your PATH.

A port is taken

midcode doesn’t use your usual port. It picks the first free one from 4310 up, so it runs beside whatever you have on 3000 or 5173. “No free ports” means the hundred ports from 4310 are all taken, which points at dev servers that never stopped: quit them.

A dev script with a fixed port is different: if that port is busy the script fails, and what it printed is in the log. Stop the other copy. From the next release, a script that only calls a tool that takes --port (rsbuild, rspack, webpack, vue-cli-service, docusaurus, gatsby, parcel, vitepress, vuepress, eleventy) and names no port is started on midcode’s port, so it no longer lands on the tool’s usual 3000, 8000 or 8080.

“How does this site run?”Next release

midcode couldn’t tell how to serve the folder. Give it a command, an address, or both, and click “Start”. On any failed start, “Change how it runs” opens the same form. Any other stack has examples for each stack.

“Nothing answers at …” means the address you gave isn’t serving. Start the site, or fix the address.

Send a report

Wherever a start fails or drags on, there are two buttons:

• –

  “Send report” opens the feedback form with what happened already written. Add what you were doing, and your email if you want an answer.

• –

  “Copy report” puts the same text on the clipboard, to paste in an email to hello@midcode.app or in an issue at github.com/agusdellaquila/midcode/issues.

“Feedback” at the top of the window sends a message at any time, with the same details unless you untick them.

What a report contains

The form shows the whole report before it goes: click “What’s sent”.

An element can’t be selected or edited

The whole project is view-only

The right panel says so, for example “Nuxt: preview and comments”. midcode has no marks for this stack, so it shows the site and lets you comment, and that’s all. What works with what says which stacks are edited, and which arrive in the next release.

“A library draws this element”

The element comes from a package in node_modules, so it isn’t written in your files. Select its parent, or the component that uses it.

“This text isn’t written there: it comes from a variable or prop”

The text is computed, or passed in from somewhere midcode couldn’t follow. midcode edits text that’s written out: in the markup, or as a string in a data file. Use “Open code” and change it there, or ask your agent. Code that midcode can edit says how to keep text editable.

“That text appears in 3 places (…)” means the same words are written in several files and midcode won’t guess which one this element shows.

“The class … isn’t written in …: it comes from a prop or a condition”

The class you’re changing isn’t written out as text in that element’s className. It’s built by code (text-${size}), comes from a prop or a constant, or is looked up (SIZES[size]). A class that is written inside a condition (active && 'bg-black', a branch of a ternary, a clsx({ … }) key) doesn’t give this message: midcode takes it out of that branch and writes the new class unconditionally. “This element’s classes come from a variable” is the same for a whole className={className}. Edit those in the code. See Tailwind CSS.

“Couldn’t find the element at … (did the file change?)”

The file was saved, by you or your agent, and the canvas hasn’t reloaded yet, so the element isn’t on the line the page remembers. Wait for the reload and do it again. “The text in the code doesn’t match the preview” is the same thing for text. If it doesn’t go away, reload the breakpoints from the top bar.

“This is written in Markdown”Next release

In a Hugo, Jekyll or Eleventy site, a heading, a paragraph or a list item of a .md file is found by its words. You can change those words, turn a heading into another level or into a paragraph, and remove it. It has no tag to hang a class or an attribute on, and it can’t be moved or have elements inserted: “its words can be changed here, not its classes or attributes. Style it from the template around it.” See Hugo, Jekyll and Eleventy.

“Item 3 of a list: editing the code changes all of them”

Not an error. One line of code draws every item of a .map(), so a class changed on one changes them all. The text of each item is edited on its own when it’s written in your data.

Pages and Site settings

There’s no plus beside “Pages”, or no globe in the top bar

In the released version, new pages and Site settings are for Next.js projects. From the next release:

• –

  The plus shows where midcode knows how the framework keeps a page: Next.js, Astro, SvelteKit, Nuxt with a pages/ folder, plain HTML, Remix, React Router, TanStack Router, Qwik City, Hugo, Jekyll, Eleventy and Laravel. Where pages are code (a Vite app without file routes, Angular, Django, Rails, Flask), make the page in code or ask your agent. Pages and navigation has what each one writes.

• –

  The globe shows where the site’s <head> is written in a file: index.html, src/app.html, public/index.html, an Astro layout, a server-rendered site’s layout. Nuxt and Docusaurus keep those settings in their config file, and midcode writes them there. WordPress keeps them in its database and Gatsby in its own config, which midcode doesn’t write: Site settings isn’t for them yet. Neither is it for a project whose <head> is built in code, such as React Router or Remix with a root.tsx.

“This is written in code here: change it in …”Next release

Outside Next.js, Site settings writes tags in your <head>. A title or description the template computes ({{ .Site.Title }}, @yield('title'), %VITE_APP_TITLE%) is shown as code and left to the code: click “Open code” and change it there.

A style doesn’t show

In a project without Tailwind 4

midcode writes the CSS for its mid: classes to midcode.css, and that file has to be imported in your app. midcode adds the import itself. When it can’t tell where, it says: “midcode added midcode.css but couldn’t tell where to import it. Import it in your app’s entry so its styles show.”

import './midcode.css'

Without Tailwind lists where the import goes in each framework.

On the deployed site, not on the canvas

midcode.css wasn’t published, or it’s out of date because classes were written outside the app. Commit it with your changes, or build it in your pipeline with the midcode package. The package needs .midcode/theme.css in the repository for your colors, fonts and text styles, and Publish doesn’t tick that file by default: tick it. Version 0.1.0 of the package doesn’t read classes written in server templates (.liquid, .php, .erb, .twig and the like): for those sites, publish the midcode.css the app wrote.

Undo says the file changed

“The file changed outside midcode, so that edit can’t be undone”. midcode only undoes an edit when the file is exactly as that edit left it. Something else wrote to it since: your editor, a formatter on save, your agent. Nothing is lost. Undo that part in your editor, or with git.

The undo history is kept until you quit midcode. How midcode works has the rules.

Publish

“None of your GitHub accounts (…) can push to …”

Before a push to GitHub, midcode asks each account it knows whether it can push to that repository: the one connected in Settings, then every account logged in to the GitHub CLI. None of them can. Log in with the one that has access:

gh auth login

That adds the account and keeps the others. Then click “Try the push again”. The commit was already made and is safe locally. After a push that worked, Publish says which account it went out as (“as …”). GitHub explains how the account is chosen.

“Committed”, not “Published”

The commit was made and the push failed, or the repository has no remote. The panel says why and offers “Try the push again”; the next time you open Publish, “Push” sends what’s waiting. midcode never forces a push.

“git isn’t installed on this Mac”

Publishing needs git. Install Apple’s command line tools, then open Publish again:

xcode-select --install

“This project doesn’t use git” means the folder isn’t a repository. Everything else in midcode works without one.

ShopifyNext release

“The storefront’s password”

Every development store sits behind a password, and the Shopify CLI can’t ask for it from inside midcode, so midcode asks. It’s in the store’s admin, under Online Store → Preferences. midcode keeps it encrypted on your Mac, never in the project.

“Shopify didn’t take that password”: check it and type it again. A wrong password also makes the CLI forget the one it remembered from your terminal.

“Connect the store” comes back

The Store view works through the Shopify CLI’s approval in the store’s admin, and Shopify’s token lasts about a day. Click “Connect” and approve again. See Store.

A database opens read-onlyNext release

The table says it’s read-only, and to turn on “Allow changes”. A database that isn’t on this Mac opens without permission to change anything. That’s on purpose: it may be the one your live site uses.

Turn on “Allow changes” beside the connection. It lasts for the session. A database on this Mac (a SQLite file, a Postgres on localhost) allows changes from the start. See Database.

The app itself

midcode doesn’t update

It only updates itself from the Applications folder. If you run it from the disk image or from Downloads, it shows “Move midcode to Applications”; if you dismissed that, drag midcode to Applications in Finder and open it from there.

The license key is refused

See Install and license.

“midcode needs a license or a trial to edit.”

The trial ended, or a license hasn’t reached the license server in 30 days. Connect and open midcode again, or paste your key.