List of frequent errors

This article attempts to list some of the more convoluted errors Augeas users might run into and give an explanation as to why they occured.

"overlapping lenses in union.put"

Here Augeas has trouble when putting a tree into a file that features nodes, which can be matched by more than one lens.

Say we have a tree

/a
/a/color = "blue"
/b
/b/color = "red"

Depending on the lens definitions for nodes a and b, the color subnode might have to be read/written differently. Yet just from looking at the tree, Augeas cannot distinguish between either color node definition. When Augeas sees a lens construct like l1|l2 it only looks at the labels of the tree node it's currently at to decide whether to use l1 or l2. In this situation, the label is identical for both nodes, hence the conflict.

How can we avoid this problem without changing the tree layout of node labels (because sometimes that is not easily possible)? We change the construct such that Augeas has to consider the depth of the tree. Without concrete examples, this will be difficult to understand, so lets expand on the previous one with these lens definitions:

let a = key "a" . [ label "color" . store /red|blue/ ]
let b = key "b" . [ label "color" . del /dark-/ "dark-" . store /red|blue/ ]
let lns = [ a | b ]

So for bs, color strings are prefixed with "dark-". When parsing a source file, Augeas can always differentiate between lenses "a" and "b". But because in either case the resulting color node is identical, saving the tree to a file fails. We make Augeas aware of the difference on node-level, by alternating between subtrees, as opposed to lenses:

let lns = [ a ]|[ b ]

"Too many matches for path expression"

First, consider using setm, the built-in function for updating several tree nodes at once, in case you actually wanted to do that - set is limited to updating exactly one node or creating a new node in case no match was found. If you intentionally used set, which failed to find a matching node for update and then aborted with this error message, then read on.

In order to explain the problem, lets start with an example tree:

/fruit[1]/a "apple"
/fruit[2]/b "orange"

Of course, this example is contrived just to demonstrate the error, since it could be easily avoided by not using additional subnodes "a" and "b" (set the value for the fruit nodes instead).

Now, when adding a new fruit with set like this, the error will trigger:

augtool> set /fruit/c[. = "peer"] "peer"
error: Too many matches for path expression

Your aim possibly was to add a new "fruit" node with a subnode "c" and value "peer", in case no such node already exists (otherwise repeating the same value is pointless, of course). Augeas will evaluate this statement like this...

1. If there is a /fruit/c with value "peer", set its value to 'peer'.
2. If there is no such node, create /fruit/c and set its value to 'peer'.

The error occurs in step two, because Augeas doesn't know which fruit node to select as parent for c. It could be, that you wanted to have c as sibling to /fruit[1]/a or /fruit[2]/b. If so, this is the appropriate statement:

augtool> set /fruit[a = "apple"]/c "peer"

If not, then you may create a new fruit subtree with c as its only child like this:

augtool> set /fruit[c = "peer"]/c "peer"

In either case, Augeas will operate this way...

1. If there is a fruit node, that has a (direct) child node with specified label and value, then create a sibling node with label "c" and value "peer".
2. If there is no such node, create a new fruit node with a child node of label "c" and value "peer".

Note that to some extend you need to know how your tree may look like, to settle on the appropriate statement. This section only serves to highlight which use cases there are and how to address them properly.