MediaWiki Troubleshooting & FAQ — 50+ Common Problems Solved

In this tutorial, you'll find solutions to the most common MediaWiki problems. This is Lesson 10 of our project: Build Your Own Documentation Wiki — your problem-solving reference.

What You'll Find Here

• 50+ common errors organized by category
• Step-by-step solutions for each
• FAQ covering topics from every lesson
• Quick-reference commands and fixes

Bookmark this page. When something breaks, come here first.

Installation Errors

"Error connecting to database"

Why: MySQL is not running, wrong credentials, or the database doesn't exist.

Fix:

1. Start MySQL (XAMPP Control Panel → MySQL → Start)
2. Wait 10 seconds, refresh the page
3. If it still fails, check your database name in LocalSettings.php:
   • Look for $wgDBname — it should be the database you created
4. Verify MySQL credentials:
   • Default XAMPP: user = root, password = (empty)
   • If you changed it, update $wgDBpassword in LocalSettings.php

"LocalSettings.php not found"

Why: You ran the installer but didn't download and place LocalSettings.php in the wiki folder.

Fix:

1. Re-run the installer by visiting http://localhost/mediawiki
2. At the end, download LocalSettings.php
3. Move it to the mediawiki folder (same directory as index.php)

White screen (blank page) after installation

Why: PHP error, missing extension, whitespace in LocalSettings.php.

Fix:

1. Open LocalSettings.php in a text editor
2. Make sure there are NO characters (not even spaces) before <?php on the first line
3. Make sure there is NO ?> at the end of the file (it's optional and causes issues)
4. Check PHP error log:
   • XAMPP: C:\xampp\php\logs\php_error_log
   • Linux: /opt/lampp/logs/php_error_log
5. Enable mbstring in php.ini: uncomment extension=mbstring

"The file you uploaded is corrupt or has an incorrect extension"

Why: File upload is disabled or file size is too large.

Fix:

1. In LocalSettings.php, add:

   $wgEnableUploads = true;
   $wgMaxUploadSize = 1024 * 1024 * 10; // 10 MB
   

2. In php.ini, increase these values:

   upload_max_filesize = 10M
   post_max_size = 10M
   

Editing Errors

Red link stays red even after creating the page

Why: Browser cache or page cache.

Fix:

• Hard refresh: Ctrl+F5 (Windows/Linux) or Cmd+Shift+R (Mac)
• Purge the page: append ?action=purge to the URL

"You do not have permission to edit this page"

Why: User group restrictions or page protection.

Fix:

1. Are you logged in? If not, log in
2. Is your account new? It might not be autoconfirmed yet (24-hour wait)
3. Is the page protected? Look for a lock icon. Only admins can edit protected pages
4. Check LocalSettings.php for permission settings

Wiki markup displays as raw text (not rendered)

Why: The page uses <nowiki> tags, or there's a syntax error.

Fix:

1. Check for <nowiki> or <pre> tags around your text
2. Make sure you're not editing inside a <code> block
3. Preview before saving — raw markup in preview means the syntax is wrong

"Edit" tab is missing

Why: You're not logged in, or the page is in a read-only namespace.

Fix:

1. Log in
2. Check if the page is in the Special: namespace (it can't be edited)
3. Some extensions hide the edit tab for non-admins

Edit conflicts

Why: Two users edited the same page at the same time.

Fix:

1. You'll see a diff showing your version and the other user's version
2. Manually merge the changes into one page
3. Avoid by editing less busy pages, or coordinate with your team

Permission Errors

"This action has been automatically identified as harmful"

Why: AbuseFilter or anti-spam measures triggered.

Fix:

1. You might be adding external links too quickly
2. If you're an admin, you can bypass the filter
3. Adjust $wgCaptchaTriggers in LocalSettings.php to be less strict

Users can register but can't edit

Why: Autoconfirmed requirement or email verification.

Fix:

1. By default, users must wait 24 hours before editing (autoconfirmed)
2. Reduce the wait: $wgAutoConfirmAge = 3600; (1 hour)
3. Or remove it: $wgAutoConfirmAge = 0;
4. If email verification is required, users must verify their email first

"Your IP address has been blocked"

Why: You were blocked by an admin, or your IP was caught in a range block.

Fix:

1. If you know the admin, contact them and ask to be unblocked
2. If this is your own wiki, log in as the admin and go to Special:Unblock
3. If you can't log in as admin, you can unblock via the command line:

   php /opt/lampp/htdocs/mediawiki/maintenance/unblock.php --unblock YourUsername
   

Extension Errors

"The requested extension does not exist"

Why: Wrong extension name in wfLoadExtension().

Fix:

1. Check the folder name in extensions/
2. The name in wfLoadExtension('Name') must match the folder name exactly
3. Example: extensions/VisualEditor/ → wfLoadExtension('VisualEditor')

VisualEditor shows "Error contacting the Parsoid server"

Why: Parsoid is not running or not configured.

Fix:

1. MediaWiki 1.42+ bundles Parsoid. Run from the mediawiki directory:

   composer install --no-dev
   

2. For older versions, you need to run Parsoid as a separate service (see the VisualEditor documentation)

Scribunto: "Lua error: ..."

Why: Your Lua code has a bug.

Fix:

1. The error message includes the line number
2. Common mistakes:
   • Missing end statement
   • os.date() used but not returned
   • Using frame.args[1] when the parameter is named differently
   • Module function not returning a string

Performance Errors

Wiki is very slow

Why: No caching, large database, too many extensions.

Fix:

1. Enable file cache: $wgUseFileCache = true;
2. Enable APCu: $wgMainCacheType = CACHE_ACCEL;
3. Disable unused extensions
4. Optimize MySQL: run OPTIMIZE TABLE on wiki tables
5. Check if a specific page loads slowly (might have too many template calls)

Pages take a long time to save

Why: Large templates, complex parser functions, or slow database.

Fix:

1. Limit template nesting depth: $wgMaxPPNodeCount = 10000; (default is higher)
2. Reduce the number of templates on a single page
3. Check MySQL performance

Search & Navigation Errors

Search returns no results

Why: Search index needs to be rebuilt.

Fix:

php /opt/lampp/htdocs/mediawiki/maintenance/rebuildall.php

Or use the CirrusSearch extension (much better search).

"The page you requested doesn't exist"

Why: Wrong URL or the page was deleted.

Fix:

1. Check the URL for typos
2. Search for the page title
3. If the page was deleted, only admins can see it in Special:DeletedPages

FAQ

Is MediaWiki free?

Yes, completely free and open source (GPL v2). No paid versions, no premium features, no hidden costs.

Can I use MediaWiki for a commercial website?

Yes. The GPL license allows commercial use. Many companies use MediaWiki for internal documentation and customer-facing wikis.

What's the difference between MediaWiki and WikiMedia?

This is the most common confusion:

• MediaWiki = the software (what you installed)
• Wikimedia = the organization that runs Wikipedia
• Wikipedia = the encyclopedia website

Think of it like: WordPress (the software) vs Automattic (the company) vs a blog (the website).

How do I change my wiki's logo?

Upload a logo image (140x140 pixels recommended) and add to LocalSettings.php:

$wgLogos = [
    '1x' => "$wgResourceBasePath/resources/assets/logo.png",
    'icon' => "$wgResourceBasePath/resources/assets/logo.png",
];

Or simpler: upload the image to your wiki and set:

$wgLogo = "$wgServer$wgScriptPath/images/your-logo.png";

How do I change the site name?

Edit the $wgSitename variable in LocalSettings.php:

$wgSitename = "My New Wiki Name";

The site name appears in the page title and in search results.

Can I import content from another wiki?

Yes. Use Special:Import to upload an XML file from another MediaWiki wiki. You can also use the importDump.php maintenance script for large imports:

php maintenance/importDump.php --conf ../LocalSettings.php < dump.xml

How do I reset my admin password?

If you can't log in, reset via the command line:

php /opt/lampp/htdocs/mediawiki/maintenance/changePassword.php --user=YourUsername --password=NewPassword

If you don't have command line access, reset through the database:

UPDATE user SET user_password = CONCAT(':B:1234567890:NewPasswordHash')
WHERE user_name = 'YourUsername';

But this requires knowing how to generate the password hash. The command line method is easier.

How do I move a wiki to a different server?

1. Back up the database (mysqldump)
2. Back up the files (tar/zip)
3. Copy both to the new server
4. Install MediaWiki on the new server (same version)
5. Restore the database
6. Restore the files
7. Update $wgServer and $wgDB* settings in LocalSettings.php
8. Run php maintenance/update.php

MediaWiki is hard. Is there an easier wiki?

Alternatives:

• DokuWiki: No database, flat-file storage, simpler markup. Great for small wikis.
• BookStack: Beautiful interface, more modern than MediaWiki. Good for documentation.
• Wiki.js: Node.js-based, modern, supports multiple editors.

Each has tradeoffs. MediaWiki is the most powerful but has the steepest learning curve. Choose based on your needs.

Where can I get help?

• MediaWiki.org — Official documentation
• MediaWiki FAQ — More questions and answers
• MediaWiki mailing list — Ask the community
• Stack Exchange — Q&A site

Final Words

You've completed all 10 lessons. You started with your first Wikipedia edit and ended with a fully functional, backed-up, extended wiki.

Here's what you built:

Your documentation wiki is ready. Add more pages, invite your team, and keep learning. Every expert was once a beginner — and you're no longer a beginner.