Common errors and fixes
Diagnose and fix the most common issues when installing and running TAW Theme.
Block not auto-discovered
Symptom: A block class exists in Blocks/ but the metabox never appears in the page editor, or BlockRegistry::render('id') renders nothing.
Cause: Composer's PSR-4 classmap is stale.
Run dump-autoload
composer dump-autoload
This must be run every time you add a new block class. TAW's block loader relies on Composer's autoloader to find class files.
Verify the folder and class names match
The folder name, file name, and class name must all match exactly:
Blocks/Hero/Hero.php → class Hero extends MetaBlock
A mismatch causes the loader to skip the block silently.
Check the namespace
The namespace must follow the PSR-4 mapping in composer.json. For a block at Blocks/Hero/Hero.php the namespace should be:
namespace TAW\Blocks\Hero;
Block assets not loading
Symptom: The block renders HTML correctly but its CSS or JS is missing on the frontend.
Check that you called queue() before get_header()
Assets must be queued before wp_head() fires. The correct pattern:
<?php
use TAW\Core\BlockRegistry;
BlockRegistry::queue('hero'); // ← before get_header()
get_header();
?>
<?php BlockRegistry::render('hero'); ?>
If you only call render() without queue(), TAW prints an inline <link> as a fallback but it lands after <head> closes, which can cause a flash of unstyled content.
Confirm the asset files exist
TAW looks for style.scss, style.css, and script.js inside the block folder. If none exist, nothing is enqueued — that's expected.
Blocks/Hero/
├── Hero.php
├── index.php
├── style.scss ← must exist for CSS to load
└── script.js ← must exist for JS to load
Check that the Vite build is up to date
In development, run npm run dev. In production, run npm run build and confirm files exist in public/build/.
Vite dev server not connecting
Symptom: The frontend loads but assets come from the production build (or fail to load entirely) even though npm run dev is running.
Confirm the dev server started on the right port
Vite defaults to port 5173. If something else is using that port, Vite picks the next available one. Check the terminal output:
VITE v7.x.x ready in Xms
➜ Local: http://localhost:5173/
If the port changed, update vite.config.js or stop the conflicting process.
Check the server URL in vite.config.js
The server.origin in vite.config.js must match the URL Vite is actually listening on. The TAW Vite bridge reads this to proxy asset URLs from WordPress.
composer create-project fails
Symptom: Composer exits with a "could not find a matching version" or "package not found" error.
Cause: The --repository flag is missing. TAW Theme is a private VCS package — Composer needs to be told where to find it.
Use the full command with the repository flag
composer create-project taw/theme my-theme \
--repository='{"type":"vcs","url":"https://github.com/Relmaur/taw-theme"}'
Emails not being delivered
Symptom: Form submissions save to WP Admin as taw_submission entries, but no email is sent.
Confirm WordPress can send mail
Mailer uses wp_mail(). If WordPress itself cannot send email, neither can TAW. Install an SMTP plugin (e.g. WP Mail SMTP) and configure a real mail provider.
Test with MailTester
Go to Tools → Test Emails in the WordPress admin. Select a template and send a test without needing a real form submission.
Check template names match compiled files
Mailer looks for templates in mails/html/{name}.html. If only an .mjml source exists and it hasn't been compiled, the mailer falls back to plain text. Run the MJML compiler or place the compiled HTML in mails/html/.
Metabox not appearing on a post
Symptom: The metabox is registered but doesn't show up in the editor for a specific post type or post.
Check the screen option
The screen key in your Metabox config must match the post type:
new Metabox([
'screen' => 'post', // 'page', 'post', or a custom post type slug
...
]);
Check the show_on callable
If you added a show_on callable, make sure it returns true for the post you're editing:
'show_on' => fn(WP_Post $post): bool => $post->ID !== 123,
Check WordPress screen options
In the page/post editor, click Screen Options (top-right) and make sure the metabox is checked. WordPress lets editors hide individual metaboxes per user.