Common problems

This page provides suggestions on how to handle various commonly seen errors and QA notices.

Handling QA notices

The ebuild.sh part of Portage includes a number of checks for common problems. These can result in a 'QA Notice' message being displayed. You must not rely upon Portage always generating these messages — they are not a substitute for proper testing and QA by developers.

Note: Some eclasses output messages in the same format. These are not covered here.

QA notice: USE flag foo not in IUSE

With the exception of 'special' flags (the arch flags and USE_EXPAND variables), all USE flags used by a package must be included in IUSE. See IUSE and USE flags.

QA notice: foo in global scope

This message occurs when various tools are inappropriately used in global scope. Remember that no external code should be run globally. Depending upon the tool in use, there are various alternatives:

sed, awk, grep, egrep, cut etc: Usually when any of the above are used in global scope, it is to manipulate a version or program name string. These should be avoided in favour of pure bash constructs. The built-in helpers of EAPI 7 are useful here. See Version and name formatting issues and Bash variable manipulation.
has_version, best_version: Calls to either of these globally indicates a serious problem. You must not have metadata varying based upon system-dependent information — see The Portage cache. You should rewrite your ebuilds to correctly use dependencies.
python, perl etc: Ebuilds are bash scripts. Offloading anything you don't know how to do in bash onto another language is not acceptable — if nothing else, because not all users will always have a full system when ebuilds are sourced.

QA notice: foo is setXid, dynamically linked and using lazy bindings

Dynamically linked setXid applications should not use lazy bindings when linking for security reasons. If this message is shown, you have a couple of options:

Modify the package's Makefile (or equivalent) to use -Wl,-z,now when linking. This solution is preferred.
Use append-ldflags (see Adding additional flags) to add -Wl,-z,now. This will affect all binaries installed, not just the setXid ones.

QA notice: ECLASS foo inherited illegally

All eclass inherits must be unconditional, or based purely upon static machine-independent criteria (PN and PV are most common here). See The Portage cache.

You may see this warning in situations where there is not actually any illegal inheritance occurring. Most commonly:

When unmerging a package which was installed using an old Portage version that did not record inheritance.
When working with eclasses in an overlay with a stale cache. See Overlay and eclasses.
When working with a stale Portage cache.

You should manually check against the rules described in The Portage cache if you see this notice locally. If you see this notice when working with a pure emerge sync over rsync setup, it is probably a genuine issue.

Handling access violations

Portage uses a sandbox for certain phases of the build process. This prevents a package from accidentally writing outside 'safe' locations. See Sandbox for details.

If a package violates the sandbox, an error such as the following will be given (assuming that the sandbox is enabled and working on the test system, which should always be the case for developer boxes):

    --------------------------- ACCESS VIOLATION SUMMARY ---------------------------
    LOG FILE = "/tmp/sandbox-app-misc_-_breakme-1-31742.log"

    open_wr:   /big-fat-red-error
    --------------------------------------------------------------------------------

The open_wr means the package tried to open for write a file that is not inside write-permitted areas. In this case, the file in question is /big-fat-red-error.

Other error messages exist for read-restricted areas — these are rarely used in ebuilds.

Access violations most commonly occur during the install phase. Sometimes it is possible to get around the sandbox violations by tricking the build system into using a safer location. See src_install and Install destinations for discussion.