WordPress Connection Troubleshooting

Issues connecting UniSync to a WordPress site for content publishing.

---

Application Password Not Working

Symptoms: Authentication fails with 401 Unauthorized when UniSync tries to publish. The Application Password was just created.

Cause: Application Passwords require WordPress 5.6+ and may be blocked by security plugins or server configuration.

Resolution:

1. Verify WordPress version: Application Passwords are built into WordPress 5.6 and later. Go to Dashboard > Updates to check.
2. Check security plugins: Plugins like Wordfence, iThemes Security, or Sucuri may disable Application Passwords or block REST API authentication. Temporarily disable them to test.
3. Check .htaccess or server config: Some hosting providers strip the Authorization header. Add this to .htaccess:

   RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

   Or for CGI/FastCGI setups:

   SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

4. Verify the password format: Application Passwords are displayed with spaces (e.g., xxxx xxxx xxxx xxxx). UniSync accepts them with or without spaces -- both work. Make sure you copied the full password when it was first displayed (it cannot be viewed again).
5. Check the username: The username must match the WordPress user that owns the Application Password. It is case-sensitive.

---

SSL Certificate Errors

Symptoms: Connection fails with SSL: CERTIFICATE_VERIFY_FAILED or SSLError. The site works fine in a browser.

Cause: The SSL certificate is self-signed, expired, or the certificate chain is incomplete.

Resolution:

1. Check the certificate from your machine:

   curl -v https://your-site.com 2>&1 | grep -i "ssl\|certificate"

2. Expired certificate: Renew via your hosting provider or Let's Encrypt.
3. Self-signed certificate: Not recommended for production. If this is a development environment, you may need to configure the backend to skip verification (not available in standard UniSync config -- fix the certificate instead).
4. Incomplete chain: Your server may not be sending intermediate certificates. Test at SSL Labs and fix the chain in your web server config.

---

CORS Issues

Symptoms: Browser console shows Access-Control-Allow-Origin errors. API calls from UniSync frontend to WordPress fail.

Cause: This typically does not affect UniSync because publishing happens server-side (backend to WordPress), not browser-to-WordPress. If you see CORS errors, the issue is likely between the browser and the UniSync backend.

Resolution:

1. Confirm the UniSync backend URL is correct in the frontend configuration.
2. If you are running the frontend and backend on different ports during development, the backend must allow the frontend's origin. This is configured in the FastAPI CORS middleware.
3. CORS errors between UniSync and WordPress are not expected -- if you encounter them, check that the WordPress URL in your environment settings points to the site directly, not through a proxy that adds CORS restrictions.

---

Authentication Failures

Symptoms: 401 Unauthorized or 403 Forbidden when publishing. Credentials were working previously.

Cause: Password was revoked, user role changed, or the WordPress user account was modified.

Resolution:

1. Log in to WordPress admin and go to Users > Your Profile > Application Passwords.
2. Check that the Application Password still exists. Revoked passwords disappear from the list.
3. If missing, create a new Application Password and update it in UniSync's environment settings.
4. Verify the user has the Editor or Administrator role (must have publish_posts and upload_files capabilities).
5. Test authentication directly:

   curl -u "username:xxxx xxxx xxxx xxxx" \
     https://your-site.com/wp-json/wp/v2/posts?per_page=1

   A successful response returns a JSON array of posts. A 401 means the credentials are wrong.

---

WordPress REST API Disabled

Symptoms: Requests to /wp-json/wp/v2/... return 404 Not Found or an HTML page instead of JSON.

Cause: The REST API is not accessible, usually due to permalink settings or a security plugin blocking it.

Resolution:

1. Check permalink settings: Go to WordPress admin > Settings > Permalinks. Select any option other than "Plain" and save. The REST API requires pretty permalinks.
2. Test the REST API directly:

   curl https://your-site.com/wp-json/wp/v2/posts?per_page=1

   If this returns HTML or a 404, the REST API is not reachable.
3. Check security plugins: Some plugins (Disable REST API, iThemes Security) can block unauthenticated or all REST API access. Whitelist the necessary endpoints or disable the restriction.
4. Check .htaccess: Custom rewrite rules may intercept /wp-json/ paths. Temporarily rename .htaccess to test.
5. Check the site URL: Ensure you are using the correct URL. If WordPress is installed in a subdirectory (e.g., https://example.com/blog), the REST API base will be https://example.com/blog/wp-json/.

---

Timeout Errors

Symptoms: Publishing or connection tests fail with timeout errors. The WordPress site is slow to respond.

Cause: The WordPress site is on slow hosting, has heavy plugins, or the server is under load.

Resolution:

1. Test response time:

   curl -o /dev/null -s -w "Total time: %{time_total}s\n" \
     https://your-site.com/wp-json/wp/v2/posts?per_page=1

   Response times over 10 seconds will likely cause timeouts.
2. Optimize WordPress:
   • Disable unused plugins.
   • Install a caching plugin (WP Super Cache, W3 Total Cache).
   • Check if the hosting plan is adequate for the site's traffic.
3. Check for large media uploads: If the agent is uploading featured images, large file sizes combined with slow upload speeds can cause timeouts. Consider optimizing images before upload.
4. Server-side limits: Some shared hosting providers set aggressive PHP execution time limits. Contact your host if REST API requests consistently time out.

---

Diagnostic Checklist

Run through this checklist when WordPress publishing is not working:

• [ ] WordPress version is 5.6 or later
• [ ] Site URL in UniSync does not have a trailing slash
• [ ] Application Password exists and was copied correctly
• [ ] Username matches the Application Password owner
• [ ] User has Editor or Administrator role
• [ ] Permalinks are set to something other than "Plain"
• [ ] REST API responds: curl https://your-site.com/wp-json/wp/v2/posts?per_page=1
• [ ] Authentication works: curl -u "user:pass" https://your-site.com/wp-json/wp/v2/posts?per_page=1
• [ ] No security plugin is blocking REST API access
• [ ] SSL certificate is valid and chain is complete