Family Archive

SV

Try the demo

JFA › Documentation › Troubleshooting

Troubleshooting

Start with the symptom, not the database.

Most JFA problems can be narrowed down without manually editing archive data. Check the environment first, preserve useful error information and make one change at a time.

First: check the basics

Before changing configuration or reinstalling anything, confirm that WordPress and JFA are running normally and note exactly what is failing.

  • Is WordPress itself loading normally?
  • Is JFA active?
  • Does JFA report a healthy genealogy provider?
  • Is private storage writable?
  • Is private-media protection reported as healthy?
  • Did the problem begin after an update, import or server change?

Keep the first useful error message.

The first specific error is usually more useful than the secondary warnings that appear after something has already failed. Save the message before retrying repeatedly or changing several settings at once.

Installation problems

WordPress refuses to install the ZIP

Make sure you downloaded the WordPress installation ZIP rather than a source-code archive or an unrelated repository export.

Also check that the server allows plugin uploads of that size and that the account you are using can install plugins.

Activation fails

Confirm that the installation meets the minimum WordPress and PHP requirements. If WordPress reports a PHP error, preserve the exact message before deactivating or reinstalling the plugin.

The first-setup guide does not appear

The onboarding flow is intended for genuinely new JFA installations. An existing archive or installation that has already been initialized should not behave like a completely fresh install.

Private storage problems

Private-media health is especially important because a configuration problem can affect either file availability or privacy.

Not writable

JFA cannot store files

The WordPress process does not have sufficient filesystem access to the configured private-storage location.

Exposed

Direct HTTP access works

Do not upload sensitive material while JFA reports the private area as directly reachable from the web.

Unknown

Protection could not be verified

Investigate why the HTTP or storage check could not complete instead of treating an unknown result as protected.

Do not fix a permissions problem with unnecessarily broad permissions.

The goal is to give the WordPress process the access it needs, not to make private archive directories writable by everyone on the server.

A photograph or document will not open

First determine whether the problem affects one file or all private media.

ONE FILE

Check the individual item

The upload may have failed, the stored file may be missing or the archive entry may point to material that is no longer available.

ALL FILES

Check storage and access

If every private file fails, investigate the storage provider, filesystem permissions, protected-media route and the current user access before editing individual archive records.

GEDCOM import problems

Do not apply an import when the preview contains unexplained large differences, identity warnings or parsing errors.

1

Keep the GEDCOM file

Do not replace or edit the only copy of the file that reproduced the problem.

2

Record the source

Note which genealogy application and export process produced the file.

3

Save the preview information

Record the relevant counts, warnings and errors before leaving the import screen.

4

Do not repeatedly apply a suspicious import

Investigate the cause first rather than hoping that repeating the same operation will correct the result.

A strange real-world GEDCOM file can be extremely useful.

If an unusual export reliably exposes a JFA import bug, a reproducible example can be more valuable to development than a vague report that “import does not work”.

A reimport appears to create duplicate people

Stop before applying further imports and confirm that you are updating the same logical genealogy source rather than creating a new import source.

Also check whether the exporter changed or removed persistent source identities. Ordinary GEDCOM XREF numbers should not be assumed to remain stable between exports.

A deliberately removed person returns

If a person was intentionally removed from JFA but still exists in the external genealogy source, a later reimport should respect the corresponding import exclusion.

If that does not happen, preserve the source file and import details and treat it as an import-lifecycle problem rather than repeatedly deleting the person after every import.

Login or access problems

The password is rejected

Confirm the exact username first. Usernames and display names are not necessarily the same. If necessary, use the normal WordPress password-reset or account-management flow rather than modifying user records directly in the database.

The account can log in but cannot access JFA

Check the account role and JFA access rather than granting full WordPress administrator privileges simply to make the error disappear.

Only one browser session behaves strangely

Try a private browser window or sign out and back in before assuming the account itself is damaged. Cached sessions and cookies can make an access problem appear inconsistent.

Pages return 404

If JFA pages or normal WordPress pages suddenly return “Not Found” while the site itself still loads, check WordPress permalink configuration before rebuilding archive data.

Opening Settings → Permalinks and saving the intended permalink structure can refresh WordPress rewrite rules after a migration or configuration change.

The archive looks wrong after changing themes

Remember that JFA and the surrounding WordPress theme are separate layers. A new WordPress theme can change the site header, typography, spacing and other outer presentation without changing the underlying JFA archive data.

Test the archive frontend after theme changes and check more than one page type before deciding that JFA itself is malfunctioning.

Before reinstalling or restoring a backup

  • Record the exact symptom and error messages.
  • Make a fresh backup if the current archive is still accessible.
  • Determine whether the problem affects WordPress generally or only JFA.
  • Check system and private-storage health.
  • Preserve any GEDCOM or uploaded file that reliably reproduces the problem.
  • Avoid manually deleting JFA database tables as a troubleshooting shortcut.

A backup is not a debugging strategy.

Restoring an older archive may make the symptom disappear while also destroying the evidence needed to understand why it happened. Record the problem first.

Reporting a useful bug

You do not need to diagnose the source code before reporting a problem. A precise description of what happened and how to reproduce it is enough to make a report valuable.

Useful bug report

  • JFA version: the exact installed version
  • WordPress version: the version running the site
  • PHP version: if known
  • What you were doing: the action immediately before the problem
  • What you expected: the result you thought should happen
  • What actually happened: the observed result
  • Error messages: copied exactly where possible
  • Reproduction: whether the problem happens every time
  • Relevant file: a non-sensitive sample or reproducible GEDCOM when appropriate

Before sharing a database dump, GEDCOM, screenshot or archive file publicly, check it for information about living relatives or other private material.

Where to report problems

Use the public Family Archive project repositories for reproducible software bugs and development-related issues.

Codeberg
GitHub mirror

Next

Release Notes →

See which JFA version is current and what changed between releases.