FAQ and Troubleshooting

FAQ & Troubleshooting

Practical answers to the most common StrataWP questions, with exact commands you can copy and paste.

This page is organized by topic. Use your browser's find (Ctrl/Cmd + F) to jump to a symptom. For deeper how-tos, see Installation & Quick Start, the CLI Reference, and Deployment.

Tip Before troubleshooting, confirm your environment meets the prerequisites: Node.js 18+ (engines require node >=18.18), pnpm 8+ (or npm), PHP 8.1+, and WordPress 6.7+. A quick version check (below) resolves a surprising number of issues.

---

Quick diagnostics

Run these first — many problems trace back to a version mismatch or a stale install.

node --version          # Should be 18 or higher
pnpm --version          # Should be 8 or higher
php --version           # Should be 8.1 or higher
wp --version            # WordPress CLI (if installed)
stratawp --version      # StrataWP CLI

Note If stratawp --version or stratawp --help errors with "command not found," the CLI isn't on your PATH. Run commands through your theme's local install instead: npx stratawp <command>. All stratawp commands work via npx inside a theme created with create-stratawp.

---

General FAQ

What is StrataWP?

StrataWP is a modern WordPress theme framework built with TypeScript, Vite, and Block Theme (FSE) architecture. It ships a CLI for scaffolding, a Vite plugin with HMR and block auto-registration, three example themes (Basic, Advanced, Store), a component explorer, headless utilities, and a full deployment/sync/rollback toolchain. See Home and Core Concepts for an overview.

Do I work inside wp-content/themes/?

No. Keep your StrataWP project in a separate development directory (for example ~/Projects/) and connect it to WordPress with a symlink. create-stratawp does this for you automatically when it detects your local WordPress site. See Installation & Quick Start.

pnpm or npm?

pnpm is recommended (the repo is pinned to pnpm@8.12.1), but npm works. To install pnpm:

npm install -g pnpm

Which dev server URL do I open?

The Vite dev server runs at http://localhost:3000, but you browse your site at your local WordPress URL (for example http://localhost:8888 or your Local by Flywheel URL). HMR is injected into the WordPress page — you don't visit port 3000 directly for normal theme development.

---

CLI & commands

New CLI commands aren't showing up after pulling the latest repo

Symptom: unknown command 'deploy' (or any newly added command), or a feature documented here is missing from stratawp --help.

Cause: Your globally installed stratawp points at an older build. Pulling new code does not rebuild or reinstall the global binary.

Fix — rebuild and reinstall the CLI from the repo:

# From the StrataWP repository root
cd packages/cli

# Build the CLI
pnpm build

# Install globally (updates the stratawp command)
npm install -g .

# Verify the update
stratawp --help

You should now see the new command listed in the help output.

Tip To update the published @stratawp/* packages inside a theme (rather than the dev CLI), use stratawp update (interactive), stratawp update --check (check only), or stratawp update --force (apply all without prompts).

stratawp: command not found

Either install the CLI globally (see above) or prefix commands with npx inside your theme directory:

npx stratawp block:new hero --category=design

---

Dev server & HMR

Port 3000 is already in use

Symptom: Error: Port 3000 is already in use

Fix — start the dev server on another port:

pnpm dev --port 3001

Hot reload isn't updating my changes

Symptom: You save a file but the browser doesn't refresh or restyle.

Fix — work through these in order:

1. Confirm the dev server is actually running and you've left its terminal open:

   pnpm dev

2. Hard-refresh the browser to clear cached assets: Cmd/Ctrl + Shift + R.
3. Check the browser console for errors (a JS/TS error can halt HMR).
4. Restart the dev server (stop with Ctrl + C, then pnpm dev again).

Note StrataWP HMR behaves differently per file type: CSS/SCSS updates instantly with no reload, TypeScript/JavaScript triggers a fast rebuild and reload, and PHP/theme.json changes trigger an automatic page refresh (these paths are watched by the Vite plugin). If only PHP changes seem "slow," that's expected — they refresh the page rather than hot-swap.

Styles aren't loading or updating

Symptom: CSS changes don't appear on the frontend.

Fix:

1. Check your SCSS for syntax errors (a failed compile keeps the old CSS).
2. Confirm the build output exists — the dist/ directory should be present.
3. Clear any WordPress caching plugin's cache.
4. Hard-refresh the browser (Cmd/Ctrl + Shift + R).

---

Blocks not registering

Symptom: A block you created doesn't appear in the editor inserter.

StrataWP's Vite plugin auto-discovers blocks by scanning src/blocks/*/block.json and generating the PHP registration. If a block isn't showing up:

1. Confirm the block lives under src/blocks/<name>/ and has a valid block.json with a unique name (for example my-theme/hero).
2. Confirm the dev server (or a production build) has run so the manifest and generated registration are up to date:

   pnpm dev      # during development
   # or
   pnpm build    # for production

3. Check the browser console and the dev-server terminal for build errors in the block's edit.tsx / render.php.
4. If you just added the block while the server was running, restart pnpm dev so the new block.json is picked up by discovery.

Tip Generate blocks with the CLI to get a correct file layout every time:

stratawp block:new hero --category=design

This scaffolds block.json, edit.tsx, render.php, and style.css under src/blocks/hero/. StrataWP blocks are dynamic (server-rendered via render.php) — there is no static save component.

---

Theme not detected or linked

My theme doesn't appear in WordPress admin

Symptom: The theme is missing from Appearance → Themes.

Fix:

1. Verify the symlink points at your theme directory:

   ls -la /path/to/wordpress/wp-content/themes/

   You should see your theme name linking back to your project folder.
2. Ensure style.css has a valid theme header (at minimum a Theme Name:).
3. Check file permissions on the project directory.

Recreating the symlink manually

If create-stratawp didn't auto-link (or you skipped it), create the symlink yourself. Run this from your theme directory:

# Confirm where you are first
pwd   # e.g. /Users/yourname/Projects/my-theme

# Link into WordPress (adjust the WordPress path for your setup)
ln -s "$(pwd)" ~/Local\ Sites/mysite/app/public/wp-content/themes/my-theme

If you hit a permission error creating the link:

sudo ln -s "$(pwd)" /path/to/wordpress/wp-content/themes/my-theme

See Installation & Quick Start for full setup, including how the CLI scans Local by Flywheel and MAMP sites.

---

Build & TypeScript errors

Build fails with errors

Symptom: Build failed with errors

Fix — clear caches and dependencies, then reinstall and rebuild:

rm -rf node_modules dist .vite
pnpm install
pnpm build

TS2307: Cannot find module (or other TypeScript errors)

Fix — reinstall dependencies and re-run the type checker:

rm -rf node_modules
pnpm install
pnpm type-check

Linting errors

Auto-fix what ESLint can:

pnpm lint --fix

---

Deployment

For full deployment setup, see Deployment and the canonical guide at docs/deployment/getting-started.md.

Deploy/auth: "Connection failed"

Fix:

• Double-check host, port, username, and credentials.
• Confirm SFTP/SSH is enabled on your server.
• Use the correct port — 21 for FTP, 22 for SFTP/SSH.
• Test the connection without deploying:

  stratawp deploy:test production

Tip Store credentials in a .env file and reference them in your deploy config with ${VAR_NAME} syntax (for example "password": "${STRATAWP_DEPLOY_PROD_PASSWORD}"). Add .env to .gitignore.

SSH key has a passphrase

Provide the passphrase via an environment variable (you'll otherwise be prompted):

STRATAWP_SSH_PASSPHRASE="your-passphrase" stratawp sync:db:pull production

In a deploy config, reference it the same way: "passphrase": "${STRATAWP_SSH_PASSPHRASE}".

"Permission denied" during deploy

• Confirm your FTP/SSH user has write permissions to the remote path.
• Verify the remote path actually exists.
• Some hosts require specific directory permissions — check with your provider.

Changed files aren't uploading ("0 files deployed")

Cause: StrataWP tracks deployments with a manifest at ~/.stratawp/deployments/{environment}.json. If it drifts out of sync with the server, changed files can be skipped.

Fix — bypass the manifest and upload everything:

stratawp deploy production --fresh

Alternative — delete the manifest so the next deploy rebuilds it:

rm ~/.stratawp/deployments/production.json

Preview a deploy before running it

stratawp deploy production --dry-run     # show what would change
stratawp deploy production --verbose     # add debug output

---

Environment & version mismatches

PHP version mismatch

Symptom: Syntax or fatal errors referencing typed properties, union types, or match expressions; the theme fails to load.

Cause: StrataWP's PHP core requires PHP 8.1 or higher.

Fix:

1. Check the PHP version your WordPress site actually uses (not just your shell):

   php --version

   In Local by Flywheel, MAMP, or your host's panel, confirm the site's PHP version is 8.1+ — it can differ from your terminal's php.
2. Upgrade the site's PHP version to 8.1 or higher, then reload.

WordPress version too old

StrataWP targets WordPress 6.7+. Older versions may lack the Block Theme (FSE) APIs the framework relies on. Update WordPress core, then re-activate the theme.

---

Still stuck? Open an issue

If none of the above resolves your problem:

1. Re-check the Quick diagnostics versions above.
2. Search existing issues — your problem may already have an answer: GitHub Issues.
3. Browse community questions in GitHub Discussions.
4. Still stuck? Open a new issue: github.com/JonImmsWordpressDev/strataWP/issues.

When you open an issue, include:

Detail	How to get it
Node.js version	node --version
pnpm version	pnpm --version
PHP version	php --version
WordPress version	Admin dashboard or wp --version
Full error message	Copy the complete stack trace
Steps to reproduce	What you ran, in order
What you've already tried	List the fixes you attempted

Tip Reproducing the problem against a fresh npx create-stratawp theme helps pinpoint whether the issue is in your code or the framework — and makes your issue much faster to triage.

---

Related pages: Installation & Quick Start · CLI Reference · Blocks, Patterns & Design Systems · Deployment · Environment Sync & Rollback