| 487 | == Troubleshooting == |
| 488 | |
| 489 | === Is setuptools properly installed? === |
| 490 | |
| 491 | Try this from the command line: |
| 492 | |
| 493 | {{{ |
| 494 | $ python -c "import pkg_resources" |
| 495 | }}} |
| 496 | |
| 497 | If you get no output, setuptools is installed. Otherwise, you'll need to install it before plugins will work in Trac. |
| 498 | |
| 499 | === Did you get the correct version of the Python egg? === |
| 500 | |
| 501 | Python eggs have the Python version encoded in their filename. For example, MyPlugin-1.0-py2.4.egg is an egg for Python 2.5, and will not be loaded if you're running a different Python version (such as 2.6 or 2.7). |
| 502 | |
| 503 | Also, verify that the egg file you downloaded is indeed a ZIP archive and not the HTML preview page instead. |
| 504 | |
| 505 | === Is the plugin enabled? === |
| 506 | |
| 507 | If you install a plugin globally (i.e. not inside the plugins directory of the Trac project environment) you will have to explicitly enable it in trac.ini. Make sure that: |
| 508 | |
| 509 | * you actually added the necessary line(s) to the [components] section |
| 510 | * the package/module names are correct |
| 511 | * the value is “enabled", not e.g. “enable” |
| 512 | |
| 513 | === Check the permissions on the egg file and on the trac.ini file === |
| 514 | |
| 515 | The user user to run Trac (either tracd or Apache) must be able to read the egg files. |
| 516 | |
| 517 | Also, it's been reported that for PosgreSQL also its user must be able to read trac.ini. |
| 518 | |
| 519 | === Check the log files === |
| 520 | |
| 521 | Open the Trac Admin tab, enable logging and set the log level to DEBUG, then watch the log file for messages about loading plugins. |
| 522 | |
| 523 | === Verify you have proper permissions === |
| 524 | |
| 525 | Some plugins, including the Test Manager ones, require you have special permissions in order to use them. |
| 526 | |
| 527 | See [wiki:TestManagerForTracPlugin#Security] for a description of the available/required permissions. |
| 528 | |
| 529 | === Is the wrong version of the plugin loading? === |
| 530 | |
| 531 | If you put your plugins inside plugins directories, and certainly if you have more than one project, you need to make sure that the correct version of the plugin is loading. Here are some basic rules: |
| 532 | |
| 533 | Only one version of the plugin can be loaded for each running Trac server (ie. each Python process). The Python namespaces and module list will be shared, and it cannot handle duplicates. Whether a plugin is enabled or disabled makes no difference. |
| 534 | |
| 535 | A globally installed plugin (typically setup.py install) will override any version in global or project plugins directories. A plugin from the global plugins directory will be located before any project plugins directory. |
| 536 | |
| 537 | '''If your Trac server hosts more than one project''' (as with TRAC_ENV_PARENT_DIR setups), then having two versions of a plugin in two different projects will give uncertain results. Only one of them will load, and the one loaded will be shared by both projects. Trac will load the first found - basically from the project that receives the first request. |
| 538 | |
| 539 | Having more than one version listed inside Python site-packages is fine (ie. installed with setup.py install) - setuptools will make sure you get the version installed most recently. However, '''don't store more than one version inside a global or project plugins directory''' - neither version number nor installed date will matter at all. There is no way to determine which one will be located first when Trac searches the directory for plugins. |
| 540 | |
| 541 | === Have you restarted Apache? === |
| 542 | |
| 543 | For Apache to sense a plugin upgrade (and sometimes even installation), it must be restarted. |
| 544 | |
| 545 | === If all of the above failed === |
| 546 | |
| 547 | OK, so the logs don't mention plugins, the egg is readable, the python version is correct and the egg has been installed globally (and is enabled in the trac.ini), you restarted Apache and it still doesn't work or give any error messages or any other indication as to why? |
| 548 | |
| 549 | Open a ticket here. The plugins maintainers (yes, it's me :-)) watch ticket notifications continuously. |
| 550 | |
| 551 | [[BR]][[BR]] |