Fix 'unused argument' in R

The error unused argument means you passed an argument the function does not accept: R matched your call against the function's parameter names and one argument was left with nowhere to go. The usual culprit is a misspelled argument name or a call that reached the wrong function, often one masked by another package.

args(matrix)                           # list the real argument names
matrix(1:6, nrow = 2)                  # nrow, not nrows
grepl("red", x, ignore.case = TRUE)    # dots in names count too
dplyr::select(df, mpg)                 # bypass a masked select()
find("select")                         # who else defines this name?
rm(select)                             # drop your own shadow copy

What this error means

R could not find a home for one of your arguments. When you call a function, R binds each argument you supply to a parameter the function declares: exact names first, then unambiguous abbreviations, then leftover values by position. An argument that survives all three rounds has nowhere to go. If the function has no ... parameter to absorb extras, R stops and names the leftover.

The shortest way to trigger it is one misspelled name:

The parentheses quote exactly what R rejected, name and value. Read that first, because the answer is usually one args() call away:

matrix() declares nrow, singular. nrows matches nothing, and there is no ... to catch it.

The four causes and their fixes

Four situations produce nearly every unused argument error. Check them in order. The first two cover most cases, and each takes under a minute to confirm.

1. A misspelled argument name

The name you typed matches no declared parameter. rnorm() declares n, mean, and sd, so one stray vowel breaks the call:

R does accept unambiguous abbreviations: rnorm(3, m = 100) runs because only mean starts with m. Partial matching only saves you when your spelling is a prefix of the real name. meen is a prefix of nothing, so it fails.

Watch for dots inside names too. Base R uses them everywhere, and dropping one produces the same error:

2. Another package masked the function

Your call reached a same-named function from a different package. When two loaded packages export the same name, the one attached last wins. The classic collision is select(): dplyr's version takes a data frame and column names, while MASS's version takes a single fitted model object.

The call is valid dplyr code. It just never reached dplyr, because library(MASS) ran later and its select() sits in front. A column name means nothing to MASS's version, so mpg comes back as unused. The fix that always works is the double colon:

3. You redefined the name yourself

A function you wrote earlier in the session shadows the package version. Objects in your workspace sit in front of every package on R's search path. Name a helper filter, select, or summary and you quietly hijack every later call:

Your two-line helper declares one parameter, x, so the condition mpg > 30 has no slot to land in. Delete your copy and the package version becomes reachable again:

4. Your own function never declared the parameter

The error is honest here: you are passing an option your function does not have. This bites when you wrap other functions and forget to pass their options along:

Declare the parameter, or accept ... and forward it to the functions inside:

When no error fires: the silent version

A function with a ... parameter swallows the typo instead of rejecting it. That is the dangerous cousin of this error. sum() adds everything in its dots, so a misspelled na.rm becomes data:

There is no error and no warning. narm = TRUE rides into ..., TRUE counts as 1, and the total silently gains one. Two more classics:

The misspelled trm is ignored, so no trimming happens and the outlier stays in; the correct trim = 0.2 returns 3. And data.frame() turns the misspelled stringsAsFactor into a new column, because the real parameter ends in s: stringsAsFactors.

Diagnose it in 30 seconds

Three commands identify the cause every time. args() shows what the function declares, find() lists every package or environment that defines the name, and environment() reveals which definition a bare call reaches:

find() reports definitions in search order, and the first entry wins. If ".GlobalEnv" tops the list, the shadow is your own. Two packages listed means masking.

How to avoid it next time

Three habits eliminate nearly every repeat.

• Namespace collision-prone verbs. In scripts that load several packages, write dplyr::select() and dplyr::filter() so load order stops mattering.
• Read the signature instead of guessing. args(fun) is instant, and ?fun documents what each parameter expects.
• Never name your own helpers after popular functions. filter, select, summary, and c are each one careless assignment away from shadowing something you need.

Try it yourself

FAQ

What does the unused argument error mean in R?

It means the function cannot accept one of the arguments in your call. R matches supplied arguments to declared parameters by exact name, then by unambiguous abbreviation, then by position. Whatever remains unmatched triggers the error, and the message quotes the rejected argument in parentheses. It does not mean your value is wrong; it means the argument's name has no match in the function you actually called.

Why does R say "could not find function %>%" instead?

That is a different failure at an earlier stage. "Could not find function" means the name resolves to nothing at all, usually because the package providing it is not loaded. Unused argument means the name resolved fine but the function rejected what you passed. For the pipe specifically, load dplyr or magrittr first, or switch to the base pipe |>, which needs no package. See could not find function for that error's own causes.

How do I get rid of "unused variable" warnings in R?

Those come from a different tool. Linters such as lintr, and check pipelines like R CMD check, warn about variables you created but never used. That is a style diagnostic, not a runtime error, and the R interpreter itself never raises it. Fix it by deleting the dead assignment or actually using the variable. The unused argument error on this page is unrelated: it is R refusing to run a call.

Why does R keep saying "object not found"?

That error concerns a variable, not a parameter. object 'x' not found means a name you referenced holds no value anywhere on the search path: a typo'd variable, a column used outside functions that do data masking, or code run out of order. Unused argument fires when the value arrived but its name matched no parameter. See object not found for the common triggers and fixes.

Related R errors

Start with the parent guide, common R errors and how to read them. The R Language Definition's argument matching section specifies the exact matching order R follows. For neighbors of this error, see could not find function for names that resolve to nothing, object not found for missing variables rather than rejected parameters, object of type closure is not subsettable for another symptom of name collisions, and functions in R for declaring parameters, defaults, and ... in your own code.