Add on product installation fails

Purpose

This document audience non-technical persons and Plone novices who need to diagnore add-on installation failures on their Plone sites.

This document does not give you an answer why your installation doesn't work, but it will explain how to extract information from Plone system and where you should take this information if you cannot find enough clues to solve the problem.

Prerequisites

• Read add-on installation tutorial
• Read how to gather necessary technical information for asking help

Add-on installation information (README.txt)

Many add-ons contain special procedures and additional installations instructions. These are always documented within product themselves and there is no generic answer for this problem.

Read product instructions on the product page at plone.org products area. See if the product contains a special documentation link or document section within the plone.org product area. Alternative some packages have instructions available on PyPi.

Some examples of additional steps

• Install some software for your operating system
• Add extends lines in buildout.cfg (example add-ons: Dexterity, Web and Mobile, others)

Failure modes

Usually add-on installation fails

• When buildout is being run (does not complete succefully)
• When Plone is being restarted in the foreground debug mode

Both failure modes will lead to a Python exception traceback. How you deal with this is explained below, with additional instructions for both buildout and Plone start-up.

Python exceptions

In the case of error, both Buildout and Plone start-ups are interrupted by Python exception. Plone will produce the exception traceback only if started from the command line The exception tracback tells you on which code line the process got sidetracker.

The exception traceback looks like this:

    snipi
    …
 args[str(name)] = field.fromUnicode(s)
  File "/Users/moo/code/yoursite/plone4/eggs/zope.configuration-3.6.0-py2.6.egg/zope/configuration/fields.py", line 139, in fromUnicode
    value = self.context.resolve(name)
  File "/Users/moo/code/yoursite/plone4/eggs/zope.configuration-3.6.0-py2.6.egg/zope/configuration/config.py", line 180, in resolve
    mod = __import__(mname, *_import_chickens)
  File "/Users/moo/code/yoursite/plone4/src/collective.externalcontent/collective/externalcontent/browser/externalsearchresultsview.py", line 12, in <module>
    from collective.batch.ploneutils import createPloneBatch
  File "/Users/moo/code/yoursite/plone4/src/collective.batch/collective/batch/__init__.py", line 1, in <module>
    raise Exception("This is the line or error")
zope.configuration.xmlconfig.ZopeXMLConfigurationError: File "/Users/moo/code/yoursite/plone4/parts/instance/etc/site.zcml", line 15.2-15.55
    ZopeXMLConfigurationError: File "/Users/moo/code/yoursite/plone4/parts/instance/etc/package-includes/007-collective.externalcontent-configure.zcml", line 1.0-1.70
    ZopeXMLConfigurationError: File "/Users/moo/code/yoursite/plone4/src/collective.externalcontent/collective/externalcontent/configure.zcml", line 12.2-12.32
    ZopeXMLConfigurationError: File "/Users/moo/code/yoursite/plone4/src/collective.externalcontent/collective/externalcontent/browser/configure.zcml", line 33.2-38.8
    Exception: This is the line or error

The relevant lines are usually the last lines and the actual message, which often is not enough to solve the problem, is on the last line (Exception: This is the line or error).

Use the exception message line to search previous incidents of this issue from Google. Below are some eaxmples what a search query could look like for add-on Products.feedfeeder if you encounter the error below

ComponentLookupError: ((<Products.Five.metaclass.documentoverriderform object at 0x711c6f0>, <HTTPRequest, URL=http://nohost>, <ATDocument at /plone/doc>), <InterfaceClass z3c.form.interfaces.IWidgets>, u'')

Try number #1

feedfeeder componentlookuperror

Another

plone componentlookuperror

… and still trying

plone "4.1" componentlookuperror

Buildout fails

Please copy the buildout command output from your console and go to the step Asking for help.

• Common buildout fail reasons and how to recover from them

Plone start-up fails

Plone start-up fails after you have added add-on in buildout.cfg, re-run buildout and you are now trying to start Plone in foreground debug mode.

Please copy Plone start-up log from your command-line window and go to the step Asking for help.

• Some common exceptions which might occur during Plone start-up

If you are using Microsoft Windows and get the message:

To run the program in the foreground, please stop it first.

Then follow these instructions first to fix the Zope process lock detection after improper shutdown.

Add on product installer does no appear in Add/remove section

Plone Site setup contains Add/remove add-on section where you need to activate the add-on for your site.

The add on installer does not appear until Plone restart. It is necessary to start Plone in foreground debug when you are dealing with troublesome add-ons. Plone will be much more verbose about the errors in the foreground mode.

Some old and unmaintained packages need zcml entry in buildout.cfg in order to appear in Add/remove section.

Asking for help

Please use Plone community guidelines asking for help. Prepare the technical logs beforehand,you have logs in your text editor for copy-pasting, and then proceed to ask for help.

• Contact the add-on author who is listed on the add-on plone.org page. The add-on author is the main person/organization responsible for the add-on and usually the only person/organization who can help you. Plone community members rarely can provide support for add-ons they didn't create themselves.
• Ask help in support chat (#plone IRC channel on freenode.net)
• Ask help in stackoverflow.com using plone tag
• Ask help on the plone-users mailing list (you need to subcribe to the mailing list before asking the question, through email or through web interface)