Troubleshooting & FAQ

Fixes for the most common Vakanssi issues, from blocked CV downloads and missing emails to jobs not showing on Google, plus quick answers to frequent questions.

This page collects the problems people run into most often, what causes each one, and how to fix it. Each section starts with the symptom, so you can scan the headings for the one that matches yours.

A CV download is blocked, or shows a 403 or 404

Candidate CVs are never public files. Vakanssi stores them in a protected storage folder inside your uploads folder and adds a .htaccess rule (a small Apache config file) that denies direct access. You can point storage to a folder outside your public site files instead with the VAKANSSI_STORAGE_DIR constant.

Either way, the only way to open a CV is through the download link Vakanssi shows in the admin, which checks that you are logged in and allowed to see applications.

So a 403 or 404 when you open the file’s own web address is the protection doing its job, not a bug.

If a download fails from the proper admin link, work through these:

The Applications board shows a red banner about the REST API

The Applications screen loads its board and list through the WordPress REST API. If a security plugin, firewall, or server rule blocks the vakanssi/v1 namespace, the screen shows a red banner (“Vakanssi can’t reach the WordPress REST API”) instead of your applications.

The board shows “Could not load the board” with a Try again button

This is a narrower, mid-session cousin of the red banner above. It means the board’s own request for applications failed after the screen had already opened, for example a dropped connection or a request that timed out, rather than the REST API being blocked outright.

Click Try again. If it keeps happening, work through the same steps as the red banner above, since a firewall or security plugin blocking the vakanssi/v1 namespace intermittently produces this too.

What Vakanssi checks on the Site Health screen

WordPress’s Tools, then Site Health screen runs Vakanssi’s own checks next to WordPress’s: candidate file protection, applications rejected as expired, scheduled tasks, emails being sent, the anti-spam challenge, the CV upload size limit, stored CV files, outbound HTTP, visitor IP source, database tables and indexes, the REST API, and whether your job pages render correctly.

Two more come from the jobs feature: whether your careers archive works with your theme, and whether your job URLs are unique on the site. Since v0.36.4, the email check says emails are being sent, not delivered, because a site can see that it handed a message to its mail server but not whether it reached an inbox.

Candidate or notification emails are not arriving

Vakanssi hands every email to WordPress’s built-in mail function, the same one WordPress uses for password resets. Delivery from there depends on your hosting. Many hosts send unauthenticated mail that lands in spam or is quietly dropped, especially when the From address is not at your own domain.

Before you assume delivery is the problem, rule out these:

My job is not appearing on Google

Getting a job into Google’s job search has two gates. First, the page must carry valid job structured data, which Vakanssi publishes only when the job is eligible. Second, even a fully eligible job is listed at Google’s discretion, and that can take time.

My open positions page is missing its listing

This happens only in one specific combination: a block theme active on WordPress older than 6.7, with the built-in /jobs/ archive turned on rather than a careers page. Vakanssi can only register its own branded template for a block theme on WordPress 6.7 or later, so on an older WordPress the archive URL falls through to your theme’s generic post list instead.

Since v0.33.29, Vakanssi notices and explains this: no search box, no department or remote filters, and no sort control, though closed roles are still hidden. Individual job pages keep their details and application form, but lose the Vakanssi wrapper classes.

Vakanssi flags it two ways: a dismissible warning notice on Hiring screens (“Vakanssi: your open-positions page is missing its listing”), and a “Vakanssi careers archive works with your theme” check on WordPress’s own Tools, then Site Health screen.

• Update WordPress to 6.7 or later. Vakanssi’s own Site Editor archive template then registers automatically, with nothing else to change.
• Or switch to a careers page instead: add the Job Listings block (or the [vakanssi_jobs] shortcode) to a page, then set it as your Careers page under Hiring, then Settings, then Jobs & Careers. A careers page renders the full listing on every WordPress version and every theme. See Your careers page and Settings reference.

Dismissing the notice only hides the reminder for you. It does not fix the underlying gap, so the Site Health check keeps failing until one of the two fixes above is applied.

My careers page went empty after I turned on job translations

This happens on a site running a translation plugin like Polylang, right after Vakanssi Jobs is switched on for translation. Polylang requires every post to carry a language, and jobs created before translation was turned on have none, so Polylang treats them as invisible: your open-positions page and careers page show nothing, and every existing job link returns “not found”.

Since v0.33.38, Vakanssi notices this and tells you. A notice on Hiring screens, visible to Administrator and HR / Compliance accounts, names how many jobs have no language assigned. Your translation plugin can set them all to your default language in one step, on its own Languages screen; nothing on the Vakanssi side needs to change.

The same release also fixed a related gap: a translated copy of a job used to keep none of its own details, no location, no employment type, no salary, and no closing date, so it never expired. A translated copy now carries its full details, so update to v0.33.38 or later if you are running an older version and translate jobs.

Site Health says my job pages are not rendering the way they should

Since v0.33.32, Tools, then Site Health carries a check called “Your open positions and job pages render correctly”, and the same row appears on Hiring, then Tools, then Status when you run the compatibility test. It fetches your real job page, and your open-positions page when the built-in archive is on, and looks at what came back.

It exists because every way these two pages break still returns a normal HTTP 200. Uptime monitoring cannot see any of it, and neither can we from here: whether they render correctly depends on your theme, your page builder and your WordPress version, not on the plugin alone.

The check is deliberately narrow. A theme that lays the listing out differently than we would passes. It only reports things that are unambiguous:

• “rendered without the application form or Apply button”: a custom single-job template is being used that has no post-content area. On an Elementor Pro Theme Builder Single, add a Post Content widget, or drag in the Application Form widget, or add [vakanssi_job_apply]. See Elementor, Divi, and block themes.
• “rendered without the Vakanssi listing”: your open-positions URL is showing your theme’s own post list rather than the Vakanssi one, so it has no search box and no filters. Usually the block-theme-on-old-WordPress case above; a careers page fixes it on any version.
• “printed more than one page title”: two things are writing the document title, normally an SEO plugin alongside a theme that also prints one. Turn the title off in one of them.
• “lost your theme’s header and footer”: the active theme has no header.php, so WordPress substituted its own built-in layout. Switching Page layout to your theme’s own template under Hiring, then Settings, then Jobs & Careers hands the job page back to the theme.

If the check reports a problem you believe is wrong, the page it fetched is the evidence: open the same URL yourself and compare.

There is a warning about protecting CV uploads

On some servers, mostly Nginx, administrators see a notice that the CV storage folder’s protection is in question. It appears because CVs live inside your public uploads folder, and either the folder answered a direct web request, or the check that tests this could not complete.

The wording tells you which. An error notice, “uploaded CV files can be downloaded directly”, means the check ran and the folder is genuinely reachable: treat this as a confirmed exposure and fix it now.

A warning, “protect uploaded CV files”, means the check itself did not finish, either because the site cannot request its own URLs, or because the folder answered “not found” instead of “forbidden”. This is an unanswered question, not proof of a leak.

The notice includes the exact server rule to fix it. Either add that rule to your server config (or send it to your hosting support and ask them to), or point storage to a folder outside your public site by defining the VAKANSSI_STORAGE_DIR constant in wp-config.php.

Confirm the result on Hiring, then Tools, then Status: click Check storage again next to the storage row to re-run the check right away, rather than waiting for it to retry on its own.

The Protected storage tile reads OK once the folder is confirmed blocked, “Not confirmed” if the check still cannot complete, or “Needs attention” if the folder is still reachable. See Firewalls & server compatibility for host-specific instructions (Nginx, Kinsta, Flywheel, Pantheon, and more).

Site Health says Vakanssi cannot store candidate files

This is a different, more serious message than the protection warning above. Since v0.32.8, Tools, then Site Health can show a critical error, “Vakanssi cannot store candidate files,” when the CV storage folder cannot be created or written at all, not just when Vakanssi cannot confirm it is sealed off from direct access. While this shows, every application with a CV attachment fails to submit.

The message names the exact folder Vakanssi tried to use, and points at the VAKANSSI_STORAGE_DIR constant in wp-config.php when your site defines one.

Site Health says some stored CV files are missing

Tools, then Site Health runs a check called “Vakanssi stored CV files are present”. It samples the 200 most recently uploaded files and confirms each one still resolves to real bytes in protected storage. A failure means some of those files could not be found.

This almost always means a storage migration or a restore-from-backup left the database and the file directory out of sync, for example a database backup restored without the matching files, or a files backup restored without the matching database. The database still has a row for the file, but the bytes themselves are gone.

Site Health flags the data-retention purge

Tools, then Site Health carries a check for the daily data-retention purge, and it tells two problems apart rather than reporting a plain yes/no.

• “The Vakanssi data-retention purge has never run”: no purge has ever completed, most often because WP-Cron is not being triggered. A brand-new install gets a grace period: for its first two days the check reads “Vakanssi scheduled tasks are set up” instead, so this only fires once that window has passed.
• “Vakanssi scheduled tasks are not running”: the purge completed before but has gone quiet for more than two days, the same underlying problem on a site that used to work.

The purge cannot be switched off by accident. Since v0.35.1, Privacy & Data Retention, the module that owns it, is always on.

For either problem, follow Going live: production setup to trigger WP-Cron from a real system cron job rather than waiting on site traffic.

Deleting an application says a file could not be removed

Deleting an application (from the candidate panel’s Delete button, the Applications list’s Delete permanently bulk action, or a GDPR erasure request) removes the stored CV file first, and only removes the application’s records once that succeeds.

If the file cannot be removed, usually a filesystem permissions problem, nothing is deleted: the application (and, for an erasure request, the candidate record) is kept exactly as it was, and you see a warning telling you a stored file could not be removed.

This is deliberate: it is safer to keep a record you can retry than to delete the database rows while the file’s bytes are still sitting on disk with nothing pointing at them.

The data reset failed, or some files could not be removed

The Danger zone card on Hiring, then Tools, then Data deletes all applicant data in one all-or-nothing step. Depending on what happened, you will see one of these notices:

• “The data reset failed and was rolled back; no data was deleted.” A database error interrupted the wipe partway through, and it was fully undone. Nothing was lost. Try again; if it keeps failing, contact support with your server’s error log.
• “Applicant data was deleted from the database … but N stored file(s) could not be removed from disk.” The database rows are gone, but the CV files were not.
  • If N is 1 or more, one or more files survived on disk, usually a filesystem permissions problem: check your server error log for the file paths and remove them by hand.
  • If N is 0, Vakanssi’s storage folder itself failed a safety check before the wipe could even start (an unsafe path, a symlink, or a folder your site does not own), so nothing was attempted and the error log will not list a specific file this time: check the storage folder’s location and permissions directly (see Firewalls & server compatibility if you set a custom VAKANSSI_STORAGE_DIR).
• “The data reset failed partway through and could not be fully rolled back on this server.” A rare case on a very old or misconfigured MySQL setup that cannot provide real transactions: some rows were already deleted before the failure and cannot be automatically undone. Review your data and re-run the reset if needed.

See Backups & data for exactly what the reset removes and keeps.

A notice says a Vakanssi module failed to load

If you see “The Vakanssi module “<name>” failed to load and was disabled for this request. Check the error log.” at the top of any wp-admin screen, one part of Vakanssi hit an unexpected error while starting up. Vakanssi isolates that failure: the broken module is skipped for that request and everything else, unrelated modules, your other plugins, the rest of the site, keeps working normally.

The notice only tells you that something failed, not why. The full error is in your site’s PHP error log (ask your host how to reach it if you are not sure, cPanel, Plesk, and most managed hosts expose one).

This notice only shows to accounts that can manage Vakanssi settings. It is separate from the REST API red banner above, that is a blocked connection to the vakanssi/v1 namespace, not a module that failed to start.

I cannot find the Import screen

Import does not have its own item in the Hiring menu; it is a one-time job, not somewhere you go daily. It lives on Hiring, then Tools, then Import, which holds the Import jobs (CSV) card and, when Vakanssi detects data from another hiring plugin, the Migrate from another plugin card.

The migration card, and the dismissible notice that links to it from your Hiring screens, only appear when there is data Vakanssi can actually import. If the Import tab itself is missing, both importers are switched off under Hiring, then Tools, then Features. See Import.

Frequently asked questions

If none of this matches, the Status tab under Hiring, then Tools is the best place to start. Its System status card reports whether your database tables, unique indexes, file storage, and job links are healthy, and its Run compatibility test button checks your application form, REST API, job pages, and anti-spam challenge for firewall, caching, or server blockers in one click.

The same tab has a Support report card that copies or downloads all of this as plain text, with no candidate personal data in it. That is exactly what you will want to share when you ask for help.

Since v0.32.7, the same snapshot also sits in a Vakanssi panel on WordPress’s own Tools, then Site Health, then Info tab, so it is already included if your host or support contact asks you to copy site info from there.

Getting help

If none of this solves it, ask in the Vakanssi support forum on WordPress.org. It is the main public support channel, and the answers help the next person with the same problem. Paste your Support report into your post: it carries no candidate personal data.

Never post anything about a real candidate in the forum, since every post there is public. For questions that involve candidate data, or about licensing, email hello@vakanssi.com instead. Security issues go to security@vakanssi.com, as described in Security.