Si vous vous intéressez aux graphes de connaissances ou aux bases de données orientées graphe, Neo4j est incontournable. Considéré comme le leader du secteur, il joue un rôle similaire à MySQL dans le monde des bases relationnelles. Pourtant, beaucoup de débutants rencontrent des difficultés dès la phase d’installation via Neo4j Desktop, l’outil officiel d’interface graphique. Des erreurs récurrentes, des tentatives infructueuses et une frustration grandissante sont fréquentes.

Le cœur du problème réside essentiellement dans deux éléments : l’environnement Java (JDK) et les variables d’environnement. Neo4j étant écrit en Java, son exécution dépend entièrement d’une machine virtuelle Java (JVM). C’est comme vouloir lancer un programme .exe sans avoir Windows installé. Le JDK est donc indispensable. Or, les versions Java évoluent rapidement, et Neo4j Desktop impose des contraintes strictes sur la compatibilité. Une version trop ancienne ou trop récente peut provoquer des erreurs imprévues, similaires à l’utilisation d’un pilote Windows 11 sur un matériel compatible uniquement avec Windows 7.

Ensuite, les variables d’environnement sont souvent mal comprises par les nouveaux utilisateurs. Elles agissent comme des panneaux indicatifs pour le système d’exploitation. Lorsque vous tapez neo4j dans un terminal, le système ne sait pas où le trouver. La variable PATH doit indiquer le chemin vers le dossier bin de Neo4j. Si cette configuration est absente ou incorrecte, le lancement échoue. Des messages tels que « cannot find or load main class » sont presque toujours dus à une mauvaise configuration de PATH ou à une incompatibilité de version JDK.

2. Préparation rigoureuse avant l’installation : choisir le bon JDK

Avant de télécharger Neo4j Desktop, assurez-vous d’avoir correctement configuré votre environnement Java. Cette étape préalable évite jusqu’à 80 % des problèmes.

2.1 Sélection de la bonne version de JDK

Pour les versions actuelles de Neo4j (4.x et 5.x), le support officiel s’arrête généralement à JDK 11 ou JDK 17. Il s’agit bien du JDK, pas du JRE. Le JDK inclut tous les outils nécessaires au développement et à l’exécution, tandis que le JRE ne permet que l’exécution.

Comment vérifier la version requise ? Consultez la documentation officielle ou la page de téléchargement de Neo4j. Elle précise souvent « Requires Java XX ». Pour les débutants, OpenJDK 11 est recommandé pour sa stabilité et sa compatibilité généralisée. Téléchargez-le depuis Adoptium (anciennement AdoptOpenJDK), une distribution open source très populaire.

2.2 Installation et validation du JDK

1. Accédez au site d’Adoptium, sélectionnez Temurin, puis choisissez la version 11, votre système d’exploitation (Windows) et l’architecture (x64).
2. Installez le fichier .msi. Évitez tout espace ou caractère non latin dans le chemin d’installation, comme D:\Logiciels\Java\. Privilégiez des chemins purs comme C:\Program Files\Eclipse Adoptium\jdk-11.0.20+8.
3. Lors de l’installation, activez l’option « Set JAVA_HOME environment variable » si disponible. Sinon, configurez-la manuellement plus tard.

Après installation, ouvrez un terminal (cmd ou PowerShell) :

java -version

Une sortie correcte affiche une version OpenJDK 11. Si l’erreur « command not found » apparaît, le chemin n’est pas configuré.

javac -version

Un résultat comme javac 11.0.20 confirme que le JDK est entièrement installé. Un message d’erreur ici signifie que seul le JRE est présent — réinstallez le JDK complet.

3. Installation et activation de Neo4j Desktop : étapes clés

3.1 Téléchargement et installation

1. Allez sur neo4j.com/download, téléchargez Neo4j Desktop. Remplissez les champs requis (nom, e-mail). Utilisez un e-mail accessible, car le code d’activation sera envoyé là-bas.
2. Immédiatement après la soumission, copiez le code d’activation (Activation Key) et sauvegardez-le dans un fichier texte. Ne fermez pas la page.
3. Exécutez le fichier .exe. Pendant l’installation, choisissez un chemin d’installation en anglais, sans espaces ni caractères spéciaux (ex: D:\Neo4j\Desktop).
4. À la première ouverture, entrez vos informations personnelles et le code d’activation. Une connexion internet stable est nécessaire pour une activation réussie.

3.2 Configuration initiale post-installation

Une fois activé, Neo4j Desktop affiche une interface intuitive. Cependant, ne lancez pas immédiatement la base de données. Configurez les variables d’environnement maintenant. Même si l’interface graphique suffit pour démarrer une isntance, ces variables sont essentielles pour :

• Résoudre les erreurs de chargement de classe.
• Permettre l’utilisation future de cypher-shell ou de drivers dans d’autres langages.

4. Configuration complète des variables d’environnement (Windows)

4.1 Définir JAVA_HOME et PATH

1. Localisez votre JDK : C:\Program Files\Eclipse Adoptium\jdk-11.0.20+8.
2. Ouvrez « Paramètres système » → « Variables d’environnement ».
3. Dans « Variables système », créez une nouvelle variable :
   • Nom : JAVA_HOME
   • Valeur : C:\Program Files\Eclipse Adoptium\jdk-11.0.20+8
4. Editez la variable Path :
   • Ajoutez une nouvelle entrée : %JAVA_HOME%\bin
   • Cela garantit que toute modification de JAVA_HOME sera automatiquement reflétée dans PATH.

4.2 Configurer NEO4J_HOME et PATH

Le chemin de Neo4j Desktop est différent de celui des bases de données. Utilisez l’interface pour localiser le dossier bin.

1. Ouvrez Neo4j Desktop.
2. Sélectionnez un projet, cliquez sur « ... » → « Terminal » ou « Open Folder » → « Bin ».
3. Copiez le chemin complet (ex: C:\Users\YourName\.Neo4jDesktop\...\installation-4.x.x\bin).
4. Créez une variable système :
   • Nom : NEO4J_HOME
   • Valeur : le chemin avant \bin (ex: C:\Users\YourName\.Neo4jDesktop\...\installation-4.x.x)
5. Modifiez Path et ajoutez : %NEO4J_HOME%\bin.

4.3 Vérification finale

**Fermez toutes les fenêtres de terminal existantes**, puis ouvrez-en une nouvelle.

java -version
neo4j --version

Une sortie correcte confirme que les variables sont bien appliquées. Si neo4j n’est pas reconnu, vérifiez que le chemin de NEO4J_HOME est exact et que %NEO4J_HOME%\bin est bien ajouté à PATH.

5. Résolution des problèmes courants

5.1 Erreur : DBMS failed to start

Le service ne démarre pas. Vérifiez les logs dans l’onglet « Logs ».

• Conflit de port : Neo4j utilise les ports 7474 (HTTP) et 7687 (Bolt). Désactivez les applications qui pourraient les utiliser (anciens Neo4j, autres bases de données).
• Service résiduel : Vérifiez dans « Services » Windows s’il existe un service nommé « Neo4j ». Arrêtez-le et désactivez-le. Supprimez complètement les anciennes installations.
• Problème de permissions ou d’espace disque : Vérifiez que le dossier C:\Users\<user>\.Neo4jDesktop</user> est accessible en écriture et qu’il reste de l’espace libre.

5.2 Erreur : « Cannot find or load main class »

Problème lié au chargement de la classe principale.

• Incompatibilité de JDK : Vérifiez avec java -version que la version actuelle correspond à celle requise (JDK 11 ou 17). Assurez-vous que %JAVA_HOME%\bin est bien placé en tête dans PATH.
• MAUVAIS NEO4J_HOME : Vérifiez que le chemin pointe vers le dossier racine de l’installation (avec lib, conf, etc.). Ouvrez le dossier %NEO4J_HOME%\lib pour confirmer l’existence de fichiers .jar.
• Fichier d’installation corrompu : Réinstallez Neo4j Desktop. Supprimez le dossier de données (.Neo4jDesktop) après sauvegarde des projets.

Les journaux dans %NEO4J_HOME%\logs ou via l’interface fournissent des indices précis. En suivant ces étapes méthodiques, la majorité des erreurs peuvent être résolues. Installer et configurer Neo4j Desktop n’est pas seulement une étape technique — c’est une excellente opportunité pour développer ses compétences en résolution de problèmes. Le moment où vous voyez apparaître le graphe des films dans votre navigateur est la récompense méritée de votre persévérance.