---
title: "__StringFromFile"
description: "JMeter __StringFromFile function reference: syntax, parameters, and practical examples for parameterizing test plans with dynamic values."
url: https://docs.jmeter.ai/functions/stringfromfile/
lastUpdated: 2026-10-01
source: docs.jmeter.ai
---

# __StringFromFile

*Also documented in context in the [full Functions and Variables reference](/user-manual/functions/#__StringFromFile).*

The StringFromFile function can be used to read strings from a text file.
This is useful for running tests that require lots of variable data.
For example when testing a banking application, 100s or 1000s of different account numbers might be required.

See also the
[CSV Data Set Config test element](/components/csv-data-set-config/)
which may be easier to use. However, that does not currently support multiple input files.

Each time it is called it reads the next line from the file.
All threads share the same instance, so different threads will get different lines.
When the end of the file is reached, it will start reading again from the beginning,
unless the maximum loop count has been reached.
If there are multiple references to the function in a test script, each will open the file independently,
even if the file names are the same.
[If the value is to be used again elsewhere, use different variable names for each function call.]

> **Note**
> Function instances are shared between threads, and the file is (re-)opened by whatever thread
> happens to need the next line of input, so using the `threadNumber` as part of the file name
> will result in unpredictable behaviour.

If an error occurs opening or reading the file, then the function returns the string “`**ERR**`”

| Name | Required | Description |
| --- | --- | --- |
| File Name | Yes | Path to the file name.             (The path can be relative to the JMeter launch directory)             If using optional sequence numbers, the path name should be suitable for passing to DecimalFormat.             See below for examples. |
| Variable Name | No | A reference name - `refName` - for reusing the value created by this function. Stored values are of the form `\${refName}`. Defaults to “`StringFromFile_`”. |
| Start sequence number | No | Initial Sequence number (if omitted, the End sequence number is treated as a loop count) |
| End   sequence number | No | Final sequence number (if omitted, sequence numbers can increase without limit) |

The file name parameter is resolved when the file is opened or re-opened.

The reference name parameter (if supplied) is resolved every time the function is executed.

**Using sequence numbers:**

When using the optional sequence numbers, the path name is used as the format string for `java.text.DecimalFormat`.
The current sequence number is passed in as the only parameter.
If the optional start number is not specified, the path name is used as is.
Useful formatting sequences are:

**`#`**
: insert the number, with no leading zeros or spaces

**`000`**
: insert the number packed out to three digits with leading zeros if necessary

#### Usage of format strings

Here are a few format strings and the corresponding sequences they will generate.

**`pin#'.'dat`**
: Will generate the digits without leading zeros and treat the dot literally like

`pin1.dat`, …, `pin9.dat`, `pin10.dat`, …, `pin9999.dat`

**`pin000'.'dat`**
: Will generate leading zeros while keeping the dot. When the numbers start having more digits
then those three digits that this format suggests, the sequence will use more digits as can be seen in

`pin001.dat`, … `pin099.dat`, …, `pin999.dat`, …, `pin9999.dat`

**`pin'.'dat#`**
: Will append digits without leading zeros while keeping the dot and generate

`pin.dat1`, …, `pin.dat9`, …, `pin.dat999`

If more digits are required than there are formatting characters, the number will be
expanded as necessary.

**To prevent a formatting character from being interpreted,
enclose it in single quotes. Note that “`.`” is a formatting character,
and must be enclosed in single quotes**
(though `#.` and `000.` work as expected in locales where the decimal point is also “`.`”)

In other locales (e.g. `fr`), the decimal point is “`,`” - which means that “`#.`”
becomes “`nnn,`”.

See the documentation for `DecimalFormat` for full details.

If the path name does not contain any special formatting characters,
the current sequence number will be appended to the name, otherwise
the number will be inserted according to the formatting instructions.

If the start sequence number is omitted, and the end sequence number is specified,
the sequence number is interpreted as a loop count, and the file will be used at most “`end`” times.
In this case the filename is not formatted.

`\${__StringFromFile(PIN#'.'DAT,,1,2)}` - reads `PIN1.DAT`, `PIN2.DAT`

`\${__StringFromFile(PIN.DAT,,,2)}` - reads `PIN.DAT` twice

Note that the “`.`” in `PIN.DAT` above should not be quoted.
In this case the start number is omitted, so the file name is used exactly as is.

## Related

- [Functions and Variables Guide](/topics/functions-and-variables/)
- [Regex Extractor Builder](/tools/regex-tester/)
- [Full Functions Reference](/user-manual/functions/)
- [Component Reference](/user-manual/component-reference/)